XPCOM:nsIEventTargetManager

Summary

Provide an interface that exposes our event queue system in a freezable and scriptable fashion.

nsIEventTarget abstracts the posting of a PLEvent to a thread event queue. It is currently implemented by nsEventQueue, nsSocketTransportService, and nsIOThreadPool. Most consumers only know how to work with a nsIEventQueue, which is only implemented by the nsEventQueue class.

Proposal

In order to hide the details of nsIEventTarget, we want to invent a new singleton interface that can be used to post "events" to a nsIEventTarget. We leverage the nsIRunnable interface to express "events." nsIRunnable was originally introduced to represent a task dispatched to a newly created thread (see nsIThread), which is conceptually very similar an event being posted to an event target.

Interface

The following is the proposed interface:

[scriptable, uuid(...)]
interface nsIEventTargetManager : nsISupports
{
  /**
   * This method dispatches a runnable to the specified event target, which
   * may correspond to a different thread.
   *
   * @param target
   *        The nsIEventTarget where the runnable will be executed.
   * @param runnable
   *        The nsIRunnable to execute.
   * @param synchronous
   *        If true, then this method will not return until the runnable
   *        has been executed.  If false, then this method will return
   *        immediately (possibly before the runnable has executed).  If
   *        the event target specifies the current thread, then it is an
   *        error for this parameter to be true.
   *
   * @throws NS_ERROR_INVALID_ARG
   *         This exception is thrown if target is null, if runnable is
   *         null, or if synchronous is set to true and target specifies
   *         an event target on the current thread.
   */
  void postEvent(in nsIEventTarget target,
                 in nsIRunnable runnable,
                 in boolean synchronous);

  /**
   * This method returns an event target by name.
   *
   * @param name
   *        The name of the event target requested.  If this value is the
   *        string "current", then the event target of the current thread
   *        is returned.
   *
   * @returns null if the named event target is undefined.
   */
  nsIEventTarget getEventTarget(in string name);

  /**
   * This method sets the event target for the current thread.  If there
   * was already an event target defined for the current thread, then that
   * event target is released, and the new event target takes its place.
   *
   * @param name
   *        The name of the event target being set.  This name must be
   *        unique, and it cannot be the string "current" since that name
   *        is reserved.
   * @param target
   *        The event target being set.
   *
   * @throws NS_ERROR_INVALID_ARG
   *         This exception is thrown if name is null, if target is null,
   *         or if name is either not unique or invalid.
   */
  void setEventTarget(in string name, in nsIEventTarget target);
};

Component

A singleton implementing this interface will be available under the following ContractID:

@mozilla.org/event-target-manager;1

C++ Utilities

And, the following C++ functional equivalents will be available via nsEventTargetUtils.h:

/**
 * This method is equivalent to nsIEventTargetManager::PostEvent
 */
nsresult NS_PostEvent(nsIEventTarget *target, nsIRunnable *runnable,
                      PRBool synchronous);
 
/**
 * This method is equivalent to nsIEventTargetManager::GetEventTarget
 */
nsresult NS_GetEventTarget(const char *name, nsIEventTarget **target);
 
/**
 * This method is equivalent to nsIEventTargetManager::SetEventTarget
 */
nsresult NS_SetEventTarget(const char *name, nsIEventTarget *target);
 
/**
 * This method is equivalent to NS_GetEventTarget("current")
 */
nsresult NS_GetCurrentEventTarget(nsIEventTarget **target);
 
/**
 * This method is equivalent to NS_GetEventTarget("main")
 */
nsresult NS_GetMainEventTarget(nsIEventTarget **target);

These functions are provided to make this API easier to use from within the Mozilla codebase and thereby encourage its use.