ppapi/c/ppb_message_loop.h

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