XPCOM:nsIEventTargetManager

Summary

I'd like to 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. It is fairly straightforward to convert most consumers over to nsIEventTarget since most consumers only need the ability to call PostEvent. However, PostEvent is not scriptable, and it relies on the PLEvent datastructure, which is not something we want to freeze.

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.

This work is being tracked by bug 315442.

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
   *        synchronous is set to true and the event target specifies the 
   *        current thread, then the runnable will be executed directly
   *        without being posted to the event target.
   *
   * @throws NS_ERROR_INVALID_ARG
   *         This exception is thrown if either target or runnable is null.
   */
  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 replaced (i.e., its name is removed from the name-to-
   * event-target mapping, and the new event target takes its place as the
   * event target for the current thread).
   *
   * @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.