Add API definition and error values for running message loops.

ppapi/api/dev/ppb_message_loop_dev.idl

+/* Copyright (c) 2011 The Chromium Authors. All rights reserved.
+ * Use of this source code is governed by a BSD-style license that can be
+ * found in the LICENSE file.
+ */
+
+/**
+ * Defines the PPB_MessageLoop_Dev interface.
+ */
+label Chrome {
+  M18 = 0.1
+},
+
+/**
+ * A message loop allows PPAPI calls to be issued on a thread. You may not
+ * issue any API calls on a thread without creating a message loop. It also
+ * allows you to post work to threads that will be issued on the message loop.
+ *
+ * To process work posted to the message loop, as well as completion callbacks
+ * for asynchronous operations, you must run the message loop via Run().
+ *
+ * Note the system manages the lifetime of the instance (and all associated
+ * resources). If the instance is deleted from the page, background threads may
+ * suddenly see their PP_Resource handles become invalid. In this case, calls
+ * will fail with PP_ERROR_BADRESOURCE. If you need to access data associated
+ * with your instance, you will probably want to create some kind of threadsafe
+ * proxy object that can handle asynchonous destruction of the instance object.
+ *
+ * Typical usage:
+ *   On the main thread:
+ *    - Create the thread yourself (using pthreads).
+ *    - Create the message loop resource.
+ *    - Pass the message loop resource to your thread's main function.
+ *    - Call PostWork() on the message loop to run functions on the thread.
+ *
+ *   From the background thread's main function:
+ *    - Call AttachToCurrentThread() with the message loop resource.
+ *    - Call Run() with the message loop resource.
+ *
+ * (You can also create the message loop resource on the background thread,
+ * but then the main thread will have no reference to it should you want to
+ * call PostWork()).
+ *
+ *
+ * The main thread has an implicitly created message loop. The main thread is
+ * the thread where PPP_InitializeModule and PPP_Instance functions are called.
+ * You can retrieve a reference to this message loop by calling
+ * GetForMainThread() or, if your code is on the main thread,
+ * GetForCurrentThread() will also work.
+ *
+ * Some special threads created by the system can not have message loops. In
+ * particular, the background thread created for audio processing has this
+ * requirement because it's intended to be highly responsive to keep up with
+ * the realtime requirements of audio processing. You can not make PPAPI calls
+ * from these threads.
+ *
+ * Once you associate a message loop for a thread, you don't have to keep a
+ * reference to it. The system will hold a reference to the message loop for as
+ * long as the thread is running. The current message loop can be retrieved
+ * using the GetCurrent() function.
+ *
+ * It is legal to create threads in your plugin without message loops, but
+ * PPAPI calls will fail.
+ *
+ * You can create a message loop object on a thread and never actually run the
+ * message loop. This will allow you to call blocking PPAPI calls (via
+ * PP_BlockUntilComplete()). If you make any asynchronous calls, the callbacks
+ * from those calls will be queued in the message loop and never run. The same
+ * thing will happen if work is scheduled after the message loop exits and
+ * the message loop is not run again.
+ */
+interface PPB_MessageLoop_Dev {
+  /**
+   * Creates a message loop resource.
+   *
+   * This may be called from any thread. After your thread starts but before
+   * issuing any other PPAPI calls on it, you must associate it with a message
+   * loop by calling AttachToCurrentThread.
+   */
+  PP_Resource Create(PP_Module module);
+
+  /**
+   * Returns a resource identifying the message loop for the main thread. The
+   * main thread always has a message loop created by the system.
+   */
+  PP_Resource GetForMainThread();
+
+  /**
+   * Returns a reference to the PPB_MessageLoop object attached to the current
+   * thread. If there is no attached message loop, the return value will be 0.
+   */
+  PP_Resource GetCurrent();

[dmichael (off chromium), 2011/12/29 19:41:21]

Does it have to be on the stack? I.e., if I've done 'AttachToCurrentThread' on
this thread, but I'm calling from the outer thread-function (not a pepper event
on this thread), what does this return?

[brettw, 2011/12/29 20:07:39]

"Once you associate a message loop for a thread, you don't have to keep a
reference to it." So this would always return the attached message loop.

+
+  /**
+   * Sets the given message loop resource as being the associated message loop
+   * for the currently running thread.
+   *
+   * You must call this function exactly once on a thread before making any
+   * PPAPI calls. A message loop can only be attached to one thread, and the
+   * message loop can not be changed later. The message loop will be attached
+   * as long as the thread is running.
+   *
+   * If this function fails, attempting to run the message loop will fail.
+   * Note that you can still post work to the message loop: it will get queued
+   * up should the message loop eventually be successfully attached and run.
+   *
+   * @return
+   *   - PP_OK: The message loop was successfully attached to the thread and is
+   *     ready to use.
+   *   - PP_ERROR_BADRESOURCE: The given message loop resource is invalid.
+   *   - PP_ERROR_INPROGRESS: The current thread already has a message loop
+   *     attached. This will always be the case for the main thread, which has
+   *     an implicit system-created message loop attached.
+   *   - PP_ERROR_WRONG_THREAD: The current thread type can not have a message
+   *     loop attached to it. See the interface level discussion about these
+   *     special threads, which include realtime audio threads.
+   */
+  int32_t AttachToCurrentThread([in] PP_Resource message_loop);
+
+  /**
+   * Runs the thread message loop. Running the message loop is required for you
+   * to get issued completion callbacks on the thread.
+   *
+   * The message loop identified by the argument must have been previously
+   * successfully attached to the current thread.
+   *
+   * You may call Run() nested inside another message loop. This nested loop
+   * will run until it's requested to quit, and control will then return to the
+   * next outermost message loop on the stack. Nested message loops can be
+   * tricky, so use with caution.
+   *
+   * You may not call Run() on the main thread's message loop. The system
+   * implicitly runs a message loop on the main thread where it issues PPP_
+   * calls, and nested message loops are not permitted on the main thread to
+   * avoid reentrancy issues with PPAPI calls.
+   *
+   * @return
+   *   - PP_OK: The message loop was successfully run. Note that on
+   *     success, the message loop will only exit when you call QuitNow() or
+   *     PostQuit().
+   *   - PP_ERROR_BADRESOURCE: The given message loop resource is invalid.
+   *   - PP_ERROR_WRONG_THREAD: You are attempting to run a message loop that
+   *     has not been successfully attached to the current thread. Call
+   *     AttachToCurrentThread().
+   *   - PP_ERROR_BLOCKS_MAIN_THREAD: You are attempting to call this function
+   *     on the main thread. This is not supported as described above.
+   */
+  int32_t Run([in] PP_Resource message_loop);

[dmichael (off chromium), 2011/12/29 19:41:21]

I think we probably want to allow a timeout and/or max-event parameter, for
applications that want to do something periodically on the outer event loop for
a thread.

[brettw, 2011/12/29 20:07:39]

If you want to run the message loop for some time, you should PostWorkEx with a
timeout using a callback that exits. This seems sufficient for me. This API is
mostly just wrapping the Chrome MesasgeLoop, and we've never needed the feature
you're requesting.

[dmichael (off chromium), 2012/01/04 04:30:26]

In Chromium, we own the message loop and can add to it whatever we please (e.g.,
histogramming). PPAPI apps don't have the option of changing the behavior of the
loop itself. Posting a timed event that quits helps, but it's not as obvious,
and there's still not a way to only run N events before quitting.

But I can't think of any really important use case for a PPAPI app. Normally,
you'd want this capability so you could handle multiple event sources on one
thread, but in our case, I think we own all the event sources anyway. So I'm
sure we can live without. I just have a feeling some apps are going to want (not
need) this.

+
+  /**
+   * Quits the message loop identified by the given resource without running
+   * pending work. This function may only be called from within the current
+   * message loop for the current thread.
+   *
+   * See also PostQuit(), which is usually more appropriate for most uses.
+   *
+   * If there are nested message loops, this will only quit the outermost one.

[yzshen1, 2011/12/30 21:08:24]

Do you mean that I can create nested message loops by calling Run() with the
same |message_loop| resource for multiple times? (This sentence seems to suggest
so.)

And I can also create nested message loops using different message loop
resources, right? (Otherwise, we don't need the |message_loop| parameter.)

[brettw, 2011/12/31 23:01:47]

Yes.
Technically not. Run says "The message loop identified by the argument must have
been previously successfully attached to the current thread." So the PP_Resource
parameters for Run and QuitNow are redundant. But I thought it was more clear to
have these since they're working "on the message loop object" for consistency.

+   *
+   * @return
+   *   - PP_OK if the message loop will be exited.
+   *   - PP_ERROR_BADRESOURCE: The given message loop resource is invalid.
+   *   - PP_ERROR_WRONG_THREAD: The message loop does not identify the message
+   *     loop registered for the current thread, or the current thread is the
+   *     main thread (which you can not exit).
+   */
+  int32_t QuitNow([in] PP_Resource message_loop);
+
+  /**
+   * Schedules work to run on the given message loop. This may be called from
+   * any thread. Posted work will be executed in the order it was posted when
+   * the message loop is Run().
+   *
+   * @arg message_loop The message loop resource.
+   *
+   * @arg callback A pointer to the completion callback to execute from the
+   * message loop.
+   *
+   * @arg callback_result_arg This value will be passed as the first parameter
+   * ("result") to the completion callback. It can be anything you want, it is
+   * not used internally.
+   *
+   * You can call this function before the message loop has started and the
+   * work will get queued until the message loop is run. If the message loop
+   * is never run, the completion callback will never be executed.
+   *
+   * You can also post work after the message loop has exited. Because the
+   * system does not know whether you plan to run the message loop on the
+   * thread again in the future, it will queue the work. If you don't run the
+   * message loop again, the requests will be lost. If your application
+   * depends on guaranteed execution, you may want to add additional signaling
+   * to avoid this race condition.
+   *
+   * @return
+   *   - PP_OK: The work was posted to the message loop's queue. As described
+   *     above, this does not mean that the work has been or will be executed
+   *     (if you never run the message loop after posting).
+   *   - PP_ERROR_BADRESOURCE: The given message loop resource is invalid.
+   *   - PP_ERROR_BADARGUMENT: The function pointer for the completion callback
+   *     is null (this will be the case if you pass PP_BlockUntilComplete()).
+   */
+  int32_t PostWork([in] PP_Resource message_loop,
+                   [in] PP_CompletionCallback callback,
+                   [in] int32_t callback_result_arg);
+
+  /**
+   * Schedules work to run on the given message loop. This is identical to
+   * PostWork() except that it allows additional control.
+   *
+   * @arg delay_ms The number of millseconds to delay execution of the given
+   * completion callback. Passing 0 means it will get queued normally and
+   * executed in order, as with PostWork().
+   *
+   * @arg prevent_nested Controls whether the callback can be executed in a
+   * nested message loop. Normal tasks posted via PostWork() will execute in
+   * nested message loops (prevent_nested = PP_FALSE). If you pass PP_TRUE,
+   * only the outermost invocation of the message loop's Run() function on the

[yzshen1, 2011/12/30 21:08:24]

I think 'outermost' on this line has different meaning from the ones on line
128, 156 and 233, isn't it? (Maybe I am confused. :))

+   * stack will execute the given completion callback. This can be useful if
+   * you need to do some cleanup (like deleting a pointer) that must be done
+   * after all code currently on the stack executes.
+   */
+  int32_t PostWorkEx([in] PP_Resource message_loop,

[viettrungluu, 2011/12/30 16:52:20]

Ugh. For the C API, I think this should be folded into PostWork().

+                     [in] PP_CompletionCallback callback,
+                     [in] int32_t callback_result,
+                     [in] int64 delay_ms,
+                     [in] PP_Bool prevent_nested);
+
+  /**
+   * Posts a quit message to the given message loop's work queue. Work posted
+   * before that point will be processed before quitting.
+   *
+   * This may be called on the message loop registered for the current thread,
+   * or it may be called on the message loop registered for another thread.
+   *
+   * If you are running nested message loops, this will only quit the outermost
+   * one. This may not be what your calling code expects, so you will need to
+   * be extra cautious if you run nested message loops.
+   *
+   * @return
+   *   - PP_OK: The request to quit was successfully posted.
+   *   - PP_ERROR_BADRESOURCE: The message loop was invalid.
+   *   - PP_ERROR_WRONG_THREAD: You are attempting to quit the main thread.
+   *     The main thread's message loop is managed by the system and can't be
+   *     quit.
+   */
+  int32_t PostQuit([in] PP_Resource message_loop);
+};

[viettrungluu, 2011/12/30 16:58:35]

I think there should be a distinction between leaving ("quitting") the message
loop and destroying (or preparing to destroy) the message loop. To be consistent
with what happens on the main thread, we should probably call all callbacks with
PP_ERROR_ABORTED, regardless of whether the message loop is actually running.
(If it's not running, this would require an additional call from the plugin on
the message loop's thread.)