Add API definition and error values for running message loops.

ppapi/c/dev/ppb_message_loop_dev.h

+/* 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.
+ */
+
+/* From dev/ppb_message_loop_dev.idl modified Tue Jan  3 12:26:22 2012. */
+
+#ifndef PPAPI_C_DEV_PPB_MESSAGE_LOOP_DEV_H_
+#define PPAPI_C_DEV_PPB_MESSAGE_LOOP_DEV_H_
+
+#include "ppapi/c/pp_bool.h"
+#include "ppapi/c/pp_completion_callback.h"
+#include "ppapi/c/pp_instance.h"
+#include "ppapi/c/pp_macros.h"
+#include "ppapi/c/pp_resource.h"
+#include "ppapi/c/pp_stdint.h"
+
+#define PPB_MESSAGELOOP_DEV_INTERFACE_0_1 "PPB_MessageLoop(Dev);0.1"
+#define PPB_MESSAGELOOP_DEV_INTERFACE PPB_MESSAGELOOP_DEV_INTERFACE_0_1
+
+/**
+ * @file
+ * Defines the PPB_MessageLoop_Dev interface.
+ */
+
+
+/**
+ * @addtogroup Interfaces
+ * @{
+ */
+/**
+ * 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.
+ *
+ *   Your callacks should look like this:
+ *      void DoMyWork(void* user_data, int32_t status) {
+ *        if (status != PP_OK)
+ *          return;
+ *        ... do your work...
+ *      }
+ *
+ * (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()).
+ *
+ *
+ * THREAD HANDLING
+ *
+ * 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.
+ *
+ *
+ * DESTRUCTION AND ERROR HANDLING
+ *
+ * Often, your application will associate memory with completion callbacks. For
+ * example, the C++ CompletionCallbackFactory has a small amount of
+ * heap-allocated memory for each callback. This memory will be leaked if the
+ * callback is never run. To avoid this memory leak, you need to be careful
+ * about error handling and shutdown.
+ *
+ * There are a number of cases where posted callbacks will never be run:
+ *
+ *  - You tear down the thread (via pthreads) without "destroying" the message
+ *    loop (via PostQuit with should_destroy = PP_TRUE). In this case, any
+ *    tasks in the message queue will be lost.
+ *
+ *  - You create a message loop, post callbacks to it, and never run it.
+ *
+ *  - You quit the message loop via QuitNow or PostQuit with should_destroy
+ *    set to PP_FALSE. In this case, the system will assume the message loop
+ *    will be run again later and keep your tasks.
+ *
+ * To do proper shutdown, call PostQuit with should_destroy = PP_TRUE. This
+ * will prohibit future work from being posted, and will allow the message loop
+ * to run until all pending tasks are run.
+ *
+ * If you post a callback to a message loop that's been destroyed, or to an
+ * invalid message loop, PostTask will return an error and will not run the
+ * callback. This is true even for callbacks with the "required" flag set,
+ * since the system may not even know what thread to issue the error callback
+ * on.
+ *
+ * Therefore, you should check for errors from PostWork and destroy any
+ * associated memory to avoid leaks. If you're using the C++
+ * CompletionCallbackFactory, use the following pattern:
+ *
+ *   pp::CompletionCallback callback = factory_.NewOptionalCallback(...);
+ *   int32_t result = message_loop.PostWork(callback);
+ *   if (result != PP_OK_COMPLETIONPENDING)
+ *     callback.Run(result);
+ *
+ * This will run the callback with an error value, and assumes that the
+ * implementation of your callback checks the "result" argument and returns
+ * immediately on error.
+ */
+struct 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_Instance instance);
+  /**
+   * 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)();
+  /**
+   * 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 or until you quit with should_destroy
+   * est to PP_TRUE.
+   *
+   * 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)(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. If you set should_destroy, all
+   * nested invocations of the message loop will be quit. 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)(PP_Resource message_loop);
+  /**
+   * 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.
+   *
+   * This does not "destroy" the message loop, so it will still be possible to
+   * post work and Run the message loop again. If you do not Run() the loop
+   * again, those completion callbacks will not be run which may cause leaks.
+   * Generally this is used to exit nested loops.
+   *
+   * See also PostQuit(), which is usually more appropriate for most uses. It
+   * allows you to properly destroy the loop and will allow pending work to
+   * complete before exiting.
+   *
+   * @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)(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 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(). In error cases, the callback may
+   * get executed before this timeout.
+   *
+   * @arg prevent_nested Controls whether the callback can be executed in a
+   * nested message loop. If you're not sure what you want, pass PP_FALSE here.
+   * 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 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.
+   *
+   *
+   * The completion callback will be called with PP_OK as the "result" parameter
+   * if it is run normally. It is good practice to check for PP_OK and return
+   * early otherwise.
+   *
+   * The "required" flag on the completion callback is ignored. If there is an
+   * error posting your callback, the error will be returned from PostWork and
+   * the callback will never be run (because there is no appropriate place to
+   * run your callback with an error without causing unexpected threading
+   * problems). If you associate memory with the completion callback (for
+   * example, you're using the C++ CompletionCallbackFactory), you will need to
+   * free this or manually run the callback. See "Desctruction and error
+   * handling" above.
+   *
+   *
+   * You can call this function before the message loop has started and the
+   * work will get queued until the message loop is run. You can also post
+   * work after the message loop has exited as long as should_destroy was
+   * PP_FALSE. It will be queued until the next invocation of Run().
+   *
+   * @return
+   *   - PP_OK_COMPLETIONPENDING: 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()).
+   *   - PP_ERROR_FAILED: The message loop has been destroyed.
+   */
+  int32_t (*PostWork)(PP_Resource message_loop,
+                      struct PP_CompletionCallback callback,
+                      int64_t delay_ms,
+                      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.
+   *
+   * @arg should_destroy Marks the message loop as being in a destroyed state
+   * and prevents further posting of messages.
+   *
+   * If you quit a message loop without setting should_destroy, it will still
+   * be attached to the thread and you can still run it again by calling Run()
+   * again. If you destroy it, it will be detached from the current thread
+   * as soon as the outermost invocation of Run() exits.
+   *
+   * If you are running nested message loops and pass PP_FALSE to
+   * should_destroy, 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. If you are destroying the message loop,
+   * all nested invocations will be quit.
+   *
+   * @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)(PP_Resource message_loop, PP_Bool should_destroy);
+};
+/**
+ * @}
+ */
+
+#endif  /* PPAPI_C_DEV_PPB_MESSAGE_LOOP_DEV_H_ */
+