1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/widget/nsIAppShell.idl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,91 @@
1.4 +/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*-
1.5 + *
1.6 + * This Source Code Form is subject to the terms of the Mozilla Public
1.7 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.8 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.9 +
1.10 +#include "nsISupports.idl"
1.11 +
1.12 +interface nsIRunnable;
1.13 +
1.14 +/**
1.15 + * Interface for the native event system layer. This interface is designed
1.16 + * to be used on the main application thread only.
1.17 + */
1.18 +[uuid(2d10ca53-f143-439a-bb2e-c1fbc71f6a05)]
1.19 +interface nsIAppShell : nsISupports
1.20 +{
1.21 + /**
1.22 + * Enter an event loop. Don't leave until exit() is called.
1.23 + */
1.24 + void run();
1.25 +
1.26 + /**
1.27 + * Exit the handle event loop
1.28 + */
1.29 + void exit();
1.30 +
1.31 + /**
1.32 + * Give hint to native event queue notification mechanism. If the native
1.33 + * platform needs to tradeoff performance vs. native event starvation this
1.34 + * hint tells the native dispatch code which to favor. The default is to
1.35 + * prevent native event starvation.
1.36 + *
1.37 + * Calls to this function may be nested. When the number of calls that pass
1.38 + * PR_TRUE is subtracted from the number of calls that pass PR_FALSE is
1.39 + * greater than 0, performance is given precedence over preventing event
1.40 + * starvation.
1.41 + *
1.42 + * The starvationDelay arg is only used when favorPerfOverStarvation is
1.43 + * PR_FALSE. It is the amount of time in milliseconds to wait before the
1.44 + * PR_FALSE actually takes effect.
1.45 + */
1.46 + void favorPerformanceHint(in boolean favorPerfOverStarvation,
1.47 + in unsigned long starvationDelay);
1.48 +
1.49 + /**
1.50 + * Suspends the use of additional platform-specific methods (besides the
1.51 + * nsIAppShell->run() event loop) to run Gecko events on the main
1.52 + * application thread. Under some circumstances these "additional methods"
1.53 + * can cause Gecko event handlers to be re-entered, sometimes leading to
1.54 + * hangs and crashes. Calls to suspendNative() and resumeNative() may be
1.55 + * nested. On some platforms (those that don't use any "additional
1.56 + * methods") this will be a no-op. Does not (in itself) stop Gecko events
1.57 + * from being processed on the main application thread. But if the
1.58 + * nsIAppShell->run() event loop is blocked when this call is made, Gecko
1.59 + * events will stop being processed until resumeNative() is called (even
1.60 + * if a plugin or library is temporarily processing events on a nested
1.61 + * event loop).
1.62 + */
1.63 + void suspendNative();
1.64 +
1.65 + /**
1.66 + * Resumes the use of additional platform-specific methods to run Gecko
1.67 + * events on the main application thread. Calls to suspendNative() and
1.68 + * resumeNative() may be nested. On some platforms this will be a no-op.
1.69 + */
1.70 + void resumeNative();
1.71 +
1.72 + /**
1.73 + * The current event loop nesting level.
1.74 + */
1.75 + readonly attribute unsigned long eventloopNestingLevel;
1.76 +
1.77 + /**
1.78 + * Allows running of a "synchronous section", in the form of an nsIRunnable
1.79 + * once the event loop has reached a "stable state". We've reached a stable
1.80 + * state when the currently executing task/event has finished, see:
1.81 + * http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#synchronous-section
1.82 + * In practice this runs aRunnable once the currently executing event
1.83 + * finishes. If called multiple times per task/event, all the runnables will
1.84 + * be executed, in the order in which runInStableState() was called.
1.85 + */
1.86 + void runInStableState(in nsIRunnable runnable);
1.87 +
1.88 + /**
1.89 + * Run the given runnable before the next iteration of the event loop (this
1.90 + * includes native events too). If a nested loop is spawned within the current
1.91 + * event then the runnable will not be run until that loop has terminated.
1.92 + */
1.93 + void runBeforeNextEvent(in nsIRunnable runnable);
1.94 +};
