| OLD | NEW |
| 1 /* Copyright (c) 2012 The Chromium Authors. All rights reserved. | 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 | 2 * Use of this source code is governed by a BSD-style license that can be |
| 3 * found in the LICENSE file. | 3 * found in the LICENSE file. |
| 4 */ | 4 */ |
| 5 | 5 |
| 6 /** | 6 /** |
| 7 * Defines the PPB_MessageLoop interface. | 7 * Defines the PPB_MessageLoop interface. |
| 8 */ | 8 */ |
| 9 label Chrome { | 9 label Chrome { |
| 10 M25 = 1.0 | 10 M25 = 1.0 |
| 11 }; | 11 }; |
| 12 | 12 |
| 13 /** | 13 /** |
| 14 * A message loop allows PPAPI calls to be issued on a thread. You may not | 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 | 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. | 16 * allows you to post work to the message loop for a thread. |
| 17 * | 17 * |
| 18 * To process work posted to the message loop, as well as completion callbacks | 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(). | 19 * for asynchronous operations, you must run the message loop via Run(). |
| 20 * | 20 * |
| 21 * Note the system manages the lifetime of the instance (and all associated | 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 | 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 | 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 | 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 | 25 * with your instance, you will probably want to create some kind of threadsafe |
| 26 * proxy object that can handle asynchonous destruction of the instance object. | 26 * proxy object that can handle asynchronous destruction of the instance object. |
| 27 * | 27 * |
| 28 * Typical usage: | 28 * Typical usage: |
| 29 * On the main thread: | 29 * On the main thread: |
| 30 * - Create the thread yourself (using pthreads). | 30 * - Create the thread yourself (using pthreads). |
| 31 * - Create the message loop resource. | 31 * - Create the message loop resource. |
| 32 * - Pass the message loop resource to your thread's main function. | 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. | 33 * - Call PostWork() on the message loop to run functions on the thread. |
| 34 * | 34 * |
| 35 * From the background thread's main function: | 35 * From the background thread's main function: |
| 36 * - Call AttachToCurrentThread() with the message loop resource. | 36 * - Call AttachToCurrentThread() with the message loop resource. |
| 37 * - Call Run() with the message loop resource. | 37 * - Call Run() with the message loop resource. |
| 38 * | 38 * |
| 39 * Your callacks should look like this: | 39 * Your callbacks should look like this: |
| 40 * void DoMyWork(void* user_data, int32_t status) { | 40 * void DoMyWork(void* user_data, int32_t status) { |
| 41 * if (status != PP_OK) { | 41 * if (status != PP_OK) { |
| 42 * Cleanup(); // e.g. free user_data. | 42 * Cleanup(); // e.g. free user_data. |
| 43 * return; | 43 * return; |
| 44 * } | 44 * } |
| 45 * ... do your work... | 45 * ... do your work... |
| 46 * } | 46 * } |
| 47 * For a C++ example, see ppapi/utility/threading/simple_thread.h | 47 * For a C++ example, see ppapi/utility/threading/simple_thread.h |
| 48 * | 48 * |
| 49 * (You can also create the message loop resource on the background thread, | 49 * (You can also create the message loop resource on the background thread, |
| (...skipping 149 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 199 | 199 |
| 200 /** | 200 /** |
| 201 * Schedules work to run on the given message loop. This may be called from | 201 * Schedules work to run on the given message loop. This may be called from |
| 202 * any thread. Posted work will be executed in the order it was posted when | 202 * any thread. Posted work will be executed in the order it was posted when |
| 203 * the message loop is Run(). | 203 * the message loop is Run(). |
| 204 * | 204 * |
| 205 * @param message_loop The message loop resource. | 205 * @param message_loop The message loop resource. |
| 206 * | 206 * |
| 207 * @param callback The completion callback to execute from the message loop. | 207 * @param callback The completion callback to execute from the message loop. |
| 208 * | 208 * |
| 209 * @param delay_ms The number of millseconds to delay execution of the given | 209 * @param delay_ms The number of milliseconds to delay execution of the given |
| 210 * completion callback. Passing 0 means it will get queued normally and | 210 * completion callback. Passing 0 means it will get queued normally and |
| 211 * executed in order. | 211 * executed in order. |
| 212 * | 212 * |
| 213 * | 213 * |
| 214 * The completion callback will be called with PP_OK as the "result" parameter | 214 * The completion callback will be called with PP_OK as the "result" parameter |
| 215 * if it is run normally. It is good practice to check for PP_OK and return | 215 * if it is run normally. It is good practice to check for PP_OK and return |
| 216 * early otherwise. | 216 * early otherwise. |
| 217 * | 217 * |
| 218 * The "required" flag on the completion callback is ignored. If there is an | 218 * The "required" flag on the completion callback is ignored. If there is an |
| 219 * error posting your callback, the error will be returned from PostWork and | 219 * error posting your callback, the error will be returned from PostWork and |
| 220 * the callback will never be run (because there is no appropriate place to | 220 * the callback will never be run (because there is no appropriate place to |
| 221 * run your callback with an error without causing unexpected threading | 221 * run your callback with an error without causing unexpected threading |
| 222 * problems). If you associate memory with the completion callback (for | 222 * problems). If you associate memory with the completion callback (for |
| 223 * example, you're using the C++ CompletionCallbackFactory), you will need to | 223 * example, you're using the C++ CompletionCallbackFactory), you will need to |
| 224 * free this or manually run the callback. See "Desctruction and error | 224 * free this or manually run the callback. See "Destruction and error |
| 225 * handling" above. | 225 * handling" above. |
| 226 * | 226 * |
| 227 * | 227 * |
| 228 * You can call this function before the message loop has started and the | 228 * You can call this function before the message loop has started and the |
| 229 * work will get queued until the message loop is run. You can also post | 229 * work will get queued until the message loop is run. You can also post |
| 230 * work after the message loop has exited as long as should_destroy was | 230 * work after the message loop has exited as long as should_destroy was |
| 231 * PP_FALSE. It will be queued until the next invocation of Run(). | 231 * PP_FALSE. It will be queued until the next invocation of Run(). |
| 232 * | 232 * |
| 233 * @return | 233 * @return |
| 234 * - PP_OK: The work was posted to the message loop's queue. As described | 234 * - PP_OK: The work was posted to the message loop's queue. As described |
| (...skipping 25 matching lines...) Expand all Loading... |
| 260 * | 260 * |
| 261 * @return | 261 * @return |
| 262 * - PP_OK: The request to quit was successfully posted. | 262 * - PP_OK: The request to quit was successfully posted. |
| 263 * - PP_ERROR_BADRESOURCE: The message loop was invalid. | 263 * - PP_ERROR_BADRESOURCE: The message loop was invalid. |
| 264 * - PP_ERROR_WRONG_THREAD: You are attempting to quit the main thread. | 264 * - PP_ERROR_WRONG_THREAD: You are attempting to quit the main thread. |
| 265 * The main thread's message loop is managed by the system and can't be | 265 * The main thread's message loop is managed by the system and can't be |
| 266 * quit. | 266 * quit. |
| 267 */ | 267 */ |
| 268 int32_t PostQuit([in] PP_Resource message_loop, PP_Bool should_destroy); | 268 int32_t PostQuit([in] PP_Resource message_loop, PP_Bool should_destroy); |
| 269 }; | 269 }; |
| OLD | NEW |