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 |