michael@0: /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
michael@0: /* vim:set ts=2 sw=2 sts=2 et cindent: */
michael@0: /* This Source Code Form is subject to the terms of the Mozilla Public
michael@0:  * License, v. 2.0. If a copy of the MPL was not distributed with this
michael@0:  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
michael@0: 
michael@0: #include "nsISupports.idl"
michael@0: 
michael@0: interface nsIRunnable;
michael@0: 
michael@0: [scriptable, uuid(4e8febe4-6631-49dc-8ac9-308c1cb9b09c)]
michael@0: interface nsIEventTarget : nsISupports
michael@0: {
michael@0:   /**
michael@0:    * Dispatch an event to this event target.  This function may be called from
michael@0:    * any thread, and it may be called re-entrantly.
michael@0:    *
michael@0:    * @param event
michael@0:    *   The event to dispatch.
michael@0:    * @param flags
michael@0:    *   The flags modifying event dispatch.  The flags are described in detail
michael@0:    *   below.
michael@0:    * 
michael@0:    * @throws NS_ERROR_INVALID_ARG
michael@0:    *   Indicates that event is null.
michael@0:    * @throws NS_ERROR_UNEXPECTED
michael@0:    *   Indicates that the thread is shutting down and has finished processing
michael@0:    * events, so this event would never run and has not been dispatched. 
michael@0:    */
michael@0:   void dispatch(in nsIRunnable event, in unsigned long flags);
michael@0: 
michael@0:   /**
michael@0:    * This flag specifies the default mode of event dispatch, whereby the event
michael@0:    * is simply queued for later processing.  When this flag is specified,
michael@0:    * dispatch returns immediately after the event is queued.
michael@0:    */
michael@0:   const unsigned long DISPATCH_NORMAL = 0;
michael@0: 
michael@0:   /**
michael@0:    * This flag specifies the synchronous mode of event dispatch, in which the
michael@0:    * dispatch method does not return until the event has been processed.
michael@0:    *
michael@0:    * NOTE: passing this flag to dispatch may have the side-effect of causing
michael@0:    * other events on the current thread to be processed while waiting for the
michael@0:    * given event to be processed.
michael@0:    */
michael@0:   const unsigned long DISPATCH_SYNC = 1;
michael@0:    
michael@0:   /**
michael@0:    * Check to see if this event target is associated with the current thread.
michael@0:    *
michael@0:    * @returns
michael@0:    *   A boolean value that if "true" indicates that events dispatched to this
michael@0:    *   event target will run on the current thread (i.e., the thread calling
michael@0:    *   this method).
michael@0:    */
michael@0:   boolean isOnCurrentThread();
michael@0: };
michael@0: 
michael@0: %{C++
michael@0: // convenient aliases:
michael@0: #define NS_DISPATCH_NORMAL nsIEventTarget::DISPATCH_NORMAL
michael@0: #define NS_DISPATCH_SYNC   nsIEventTarget::DISPATCH_SYNC
michael@0: %}