Torne (Richard Coles) | 2a99a7e | 2013-03-28 15:31:22 +0000 | [diff] [blame] | 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 | |
Torne (Richard Coles) | 868fa2f | 2013-06-11 10:57:03 +0100 | [diff] [blame] | 6 | /* From ppb_message_loop.idl modified Thu May 9 14:59:57 2013. */ |
Torne (Richard Coles) | 2a99a7e | 2013-03-28 15:31:22 +0000 | [diff] [blame] | 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 |
Torne (Richard Coles) | c2e0dbd | 2013-05-09 18:35:53 +0100 | [diff] [blame] | 44 | * proxy object that can handle asynchronous destruction of the instance object. |
Torne (Richard Coles) | 2a99a7e | 2013-03-28 15:31:22 +0000 | [diff] [blame] | 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 | * |
Torne (Richard Coles) | c2e0dbd | 2013-05-09 18:35:53 +0100 | [diff] [blame] | 57 | * Your callbacks should look like this: |
Torne (Richard Coles) | 868fa2f | 2013-06-11 10:57:03 +0100 | [diff] [blame] | 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 |
Torne (Richard Coles) | 2a99a7e | 2013-03-28 15:31:22 +0000 | [diff] [blame] | 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 |
Torne (Richard Coles) | 5d1f7b1 | 2014-02-21 12:16:55 +0000 | [diff] [blame] | 79 | * GetForMainThread() or, if your code is on the main thread, GetCurrent() will |
| 80 | * also work. |
Torne (Richard Coles) | 2a99a7e | 2013-03-28 15:31:22 +0000 | [diff] [blame] | 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: |
Torne (Richard Coles) | 868fa2f | 2013-06-11 10:57:03 +0100 | [diff] [blame] | 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 |
Torne (Richard Coles) | 2a99a7e | 2013-03-28 15:31:22 +0000 | [diff] [blame] | 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 | * |
Torne (Richard Coles) | c2e0dbd | 2013-05-09 18:35:53 +0100 | [diff] [blame] | 224 | * @param delay_ms The number of milliseconds to delay execution of the given |
Torne (Richard Coles) | 2a99a7e | 2013-03-28 15:31:22 +0000 | [diff] [blame] | 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 |
Torne (Richard Coles) | c2e0dbd | 2013-05-09 18:35:53 +0100 | [diff] [blame] | 239 | * free this or manually run the callback. See "Destruction and error |
Torne (Richard Coles) | 2a99a7e | 2013-03-28 15:31:22 +0000 | [diff] [blame] | 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 | |