ppapi/api/ppb_message_loop.idl

   1 /* Copyright (c) 2012 The Chromium Authors. All rights reserved.
   2  * Use of this source code is governed by a BSD-style license that can be
   3  * found in the LICENSE file.
   4  */
   5
   6 /**
   7  * Defines the PPB_MessageLoop interface.
   8  */
   9 label Chrome {
  10   M25 = 1.0
  11 };
  12
  13 /**
  14  * A message loop allows PPAPI calls to be issued on a thread. You may not
  15  * issue any API calls on a thread without creating a message loop. It also
  16  * allows you to post work to the message loop for a thread.
  17  *
  18  * To process work posted to the message loop, as well as completion callbacks
  19  * for asynchronous operations, you must run the message loop via Run().
  20  *
  21  * Note the system manages the lifetime of the instance (and all associated
  22  * resources). If the instance is deleted from the page, background threads may
  23  * suddenly see their PP_Resource handles become invalid. In this case, calls
  24  * will fail with PP_ERROR_BADRESOURCE. If you need to access data associated
  25  * with your instance, you will probably want to create some kind of threadsafe
  26  * proxy object that can handle asynchronous destruction of the instance object.
  27  *
  28  * Typical usage:
  29  *   On the main thread:
  30  *    - Create the thread yourself (using pthreads).
  31  *    - Create the message loop resource.
  32  *    - Pass the message loop resource to your thread's main function.
  33  *    - Call PostWork() on the message loop to run functions on the thread.
  34  *
  35  *   From the background thread's main function:
  36  *    - Call AttachToCurrentThread() with the message loop resource.
  37  *    - Call Run() with the message loop resource.
  38  *
  39  *   Your callbacks should look like this:
  40  *   @code
  41  *   void DoMyWork(void* user_data, int32_t status) {
  42  *     if (status != PP_OK) {
  43  *       Cleanup();  // e.g. free user_data.
  44  *       return;
  45  *     }
  46  *     ... do your work...
  47  *   }
  48  *   @endcode
  49  * For a C++ example, see ppapi/utility/threading/simple_thread.h
  50  *
  51  * (You can also create the message loop resource on the background thread,
  52  * but then the main thread will have no reference to it should you want to
  53  * call PostWork()).
  54  *
  55  *
  56  * THREAD HANDLING
  57  *
  58  * The main thread has an implicitly created message loop. The main thread is
  59  * the thread where PPP_InitializeModule and PPP_Instance functions are called.
  60  * You can retrieve a reference to this message loop by calling
  61  * GetForMainThread() or, if your code is on the main thread, GetCurrent() will
  62  * also work.
  63  *
  64  * Some special threads created by the system can not have message loops. In
  65  * particular, the background thread created for audio processing has this
  66  * requirement because it's intended to be highly responsive to keep up with
  67  * the realtime requirements of audio processing. You can not make PPAPI calls
  68  * from these threads.
  69  *
  70  * Once you associate a message loop with a thread, you don't have to keep a
  71  * reference to it. The system will hold a reference to the message loop for as
  72  * long as the thread is running. The current message loop can be retrieved
  73  * using the GetCurrent() function.
  74  *
  75  * It is legal to create threads in your plugin without message loops, but
  76  * PPAPI calls will fail unless explicitly noted in the documentation.
  77  *
  78  * You can create a message loop object on a thread and never actually run the
  79  * message loop. This will allow you to call blocking PPAPI calls (via
  80  * PP_BlockUntilComplete()). If you make any asynchronous calls, the callbacks
  81  * from those calls will be queued in the message loop and never run. The same
  82  * thing will happen if work is scheduled after the message loop exits and
  83  * the message loop is not run again.
  84  *
  85  *
  86  * DESTRUCTION AND ERROR HANDLING
  87  *
  88  * Often, your application will associate memory with completion callbacks. For
  89  * example, the C++ CompletionCallbackFactory has a small amount of
  90  * heap-allocated memory for each callback. This memory will be leaked if the
  91  * callback is never run. To avoid this memory leak, you need to be careful
  92  * about error handling and shutdown.
  93  *
  94  * There are a number of cases where posted callbacks will never be run:
  95  *
  96  *  - You tear down the thread (via pthreads) without "destroying" the message
  97  *    loop (via PostQuit with should_destroy = PP_TRUE). In this case, any
  98  *    tasks in the message queue will be lost.
  99  *
 100  *  - You create a message loop, post callbacks to it, and never run it.
 101  *
 102  *  - You quit the message loop via PostQuit with should_destroy set to
 103  *    PP_FALSE. In this case, the system will assume the message loop will be
 104  *    run again later and keep your tasks.
 105  *
 106  * To do proper shutdown, call PostQuit with should_destroy = PP_TRUE. This
 107  * will prohibit future work from being posted, and will allow the message loop
 108  * to run until all pending tasks are run.
 109  *
 110  * If you post a callback to a message loop that's been destroyed, or to an
 111  * invalid message loop, PostWork will return an error and will not run the
 112  * callback. This is true even for callbacks with the "required" flag set,
 113  * since the system may not even know what thread to issue the error callback
 114  * on.
 115  *
 116  * Therefore, you should check for errors from PostWork and destroy any
 117  * associated memory to avoid leaks. If you're using the C++
 118  * CompletionCallbackFactory, use the following pattern:
 119  * @code
 120  * pp::CompletionCallback callback = factory_.NewOptionalCallback(...);
 121  * int32_t result = message_loop.PostWork(callback);
 122  * if (result != PP_OK)
 123  *   callback.Run(result);
 124  * @endcode
 125  * This will run the callback with an error value, and assumes that the
 126  * implementation of your callback checks the "result" argument and returns
 127  * immediately on error.
 128  */
 129 interface PPB_MessageLoop {
 130   /**
 131    * Creates a message loop resource.
 132    *
 133    * This may be called from any thread. After your thread starts but before
 134    * issuing any other PPAPI calls on it, you must associate it with a message
 135    * loop by calling AttachToCurrentThread.
 136    */
 137   PP_Resource Create(PP_Instance instance);
 138
 139   /**
 140    * Returns a resource identifying the message loop for the main thread. The
 141    * main thread always has a message loop created by the system.
 142    */
 143   PP_Resource GetForMainThread();
 144
 145   /**
 146    * Returns a reference to the PPB_MessageLoop object attached to the current
 147    * thread. If there is no attached message loop, the return value will be 0.
 148    */
 149   PP_Resource GetCurrent();
 150
 151   /**
 152    * Sets the given message loop resource as being the associated message loop
 153    * for the currently running thread.
 154    *
 155    * You must call this function exactly once on a thread before making any
 156    * PPAPI calls. A message loop can only be attached to one thread, and the
 157    * message loop can not be changed later. The message loop will be attached
 158    * as long as the thread is running or until you quit with should_destroy
 159    * set to PP_TRUE.
 160    *
 161    * If this function fails, attempting to run the message loop will fail.
 162    * Note that you can still post work to the message loop: it will get queued
 163    * up should the message loop eventually be successfully attached and run.
 164    *
 165    * @return
 166    *   - PP_OK: The message loop was successfully attached to the thread and is
 167    *     ready to use.
 168    *   - PP_ERROR_BADRESOURCE: The given message loop resource is invalid.
 169    *   - PP_ERROR_INPROGRESS: The current thread already has a message loop
 170    *     attached. This will always be the case for the main thread, which has
 171    *     an implicit system-created message loop attached.
 172    *   - PP_ERROR_WRONG_THREAD: The current thread type can not have a message
 173    *     loop attached to it. See the interface level discussion about these
 174    *     special threads, which include realtime audio threads.
 175    */
 176   int32_t AttachToCurrentThread([in] PP_Resource message_loop);
 177
 178   /**
 179    * Runs the thread message loop. Running the message loop is required for you
 180    * to get issued completion callbacks on the thread.
 181    *
 182    * The message loop identified by the argument must have been previously
 183    * successfully attached to the current thread.
 184    *
 185    * You may not run nested message loops. Since the main thread has an
 186    * implicit message loop that the system runs, you may not call Run on the
 187    * main thread.
 188    *
 189    * @return
 190    *   - PP_OK: The message loop was successfully run. Note that on
 191    *     success, the message loop will only exit when you call PostQuit().
 192    *   - PP_ERROR_BADRESOURCE: The given message loop resource is invalid.
 193    *   - PP_ERROR_WRONG_THREAD: You are attempting to run a message loop that
 194    *     has not been successfully attached to the current thread. Call
 195    *     AttachToCurrentThread().
 196    *   - PP_ERROR_INPROGRESS: You are attempting to call Run in a nested
 197    *     fashion (Run is already on the stack). This will occur if you attempt
 198    *     to call run on the main thread's message loop (see above).
 199    */
 200   int32_t Run([in] PP_Resource message_loop);
 201
 202   /**
 203    * Schedules work to run on the given message loop. This may be called from
 204    * any thread. Posted work will be executed in the order it was posted when
 205    * the message loop is Run().
 206    *
 207    * @param message_loop The message loop resource.
 208    *
 209    * @param callback The completion callback to execute from the message loop.
 210    *
 211    * @param delay_ms The number of milliseconds to delay execution of the given
 212    * completion callback. Passing 0 means it will get queued normally and
 213    * executed in order.
 214    *
 215    *
 216    * The completion callback will be called with PP_OK as the "result" parameter
 217    * if it is run normally. It is good practice to check for PP_OK and return
 218    * early otherwise.
 219    *
 220    * The "required" flag on the completion callback is ignored. If there is an
 221    * error posting your callback, the error will be returned from PostWork and
 222    * the callback will never be run (because there is no appropriate place to
 223    * run your callback with an error without causing unexpected threading
 224    * problems). If you associate memory with the completion callback (for
 225    * example, you're using the C++ CompletionCallbackFactory), you will need to
 226    * free this or manually run the callback. See "Destruction and error
 227    * handling" above.
 228    *
 229    *
 230    * You can call this function before the message loop has started and the
 231    * work will get queued until the message loop is run. You can also post
 232    * work after the message loop has exited as long as should_destroy was
 233    * PP_FALSE. It will be queued until the next invocation of Run().
 234    *
 235    * @return
 236    *   - PP_OK: The work was posted to the message loop's queue. As described
 237    *     above, this does not mean that the work has been or will be executed
 238    *     (if you never run the message loop after posting).
 239    *   - PP_ERROR_BADRESOURCE: The given message loop resource is invalid.
 240    *   - PP_ERROR_BADARGUMENT: The function pointer for the completion callback
 241    *     is null (this will be the case if you pass PP_BlockUntilComplete()).
 242    *   - PP_ERROR_FAILED: The message loop has been destroyed.
 243    */
 244   int32_t PostWork([in] PP_Resource message_loop,
 245                    [in] PP_CompletionCallback callback,
 246                    [in] int64_t delay_ms);
 247
 248   /**
 249    * Posts a quit message to the given message loop's work queue. Work posted
 250    * before that point will be processed before quitting.
 251    *
 252    * This may be called on the message loop registered for the current thread,
 253    * or it may be called on the message loop registered for another thread. It
 254    * is an error to attempt to PostQuit() the main thread loop.
 255    *
 256    * @param should_destroy Marks the message loop as being in a destroyed state
 257    * and prevents further posting of messages.
 258    *
 259    * If you quit a message loop without setting should_destroy, it will still
 260    * be attached to the thread and you can still run it again by calling Run()
 261    * again. If you destroy it, it will be detached from the current thread.
 262    *
 263    * @return
 264    *   - PP_OK: The request to quit was successfully posted.
 265    *   - PP_ERROR_BADRESOURCE: The message loop was invalid.
 266    *   - PP_ERROR_WRONG_THREAD: You are attempting to quit the main thread.
 267    *     The main thread's message loop is managed by the system and can't be
 268    *     quit.
 269    */
 270   int32_t PostQuit([in] PP_Resource message_loop, PP_Bool should_destroy);
 271 };