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 #ifndef PPAPI_CPP_MESSAGE_LOOP_H_ | 5 #ifndef PPAPI_CPP_MESSAGE_LOOP_H_ |
6 #define PPAPI_CPP_MESSAGE_LOOP_H_ | 6 #define PPAPI_CPP_MESSAGE_LOOP_H_ |
7 | 7 |
8 #include "ppapi/cpp/resource.h" | 8 #include "ppapi/cpp/resource.h" |
9 | 9 |
10 namespace pp { | 10 namespace pp { |
11 | 11 |
12 class CompletionCallback; | 12 class CompletionCallback; |
13 class InstanceHandle; | 13 class InstanceHandle; |
14 | 14 |
15 /// A message loop allows PPAPI calls to be issued on a thread. You may not | 15 /// A message loop allows PPAPI calls to be issued on a thread. You may not |
16 /// issue any API calls on a thread without creating a message loop. It also | 16 /// issue any API calls on a thread without creating a message loop. It also |
17 /// allows you to post work to the message loop for a thread. | 17 /// allows you to post work to the message loop for a thread. |
18 /// | 18 /// |
19 /// To process work posted to the message loop, as well as completion callbacks | 19 /// To process work posted to the message loop, as well as completion callbacks |
20 /// for asynchronous operations, you must run the message loop via Run(). | 20 /// for asynchronous operations, you must run the message loop via Run(). |
21 /// | 21 /// |
22 /// Note the system manages the lifetime of the instance (and all associated | 22 /// Note the system manages the lifetime of the instance (and all associated |
23 /// resources). If the instance is deleted from the page, background threads may | 23 /// resources). If the instance is deleted from the page, background threads may |
24 /// suddenly see their PP_Resource handles become invalid. In this case, calls | 24 /// suddenly see their PP_Resource handles become invalid. In this case, calls |
25 /// will fail with PP_ERROR_BADRESOURCE. If you need to access data associated | 25 /// will fail with PP_ERROR_BADRESOURCE. If you need to access data associated |
26 /// with your instance, you will probably want to create some kind of threadsafe | 26 /// with your instance, you will probably want to create some kind of threadsafe |
27 /// proxy object that can handle asynchonous destruction of the instance object. | 27 /// proxy object that can handle asynchronous destruction of the instance |
| 28 /// object. |
28 /// | 29 /// |
29 /// Typical usage: | 30 /// Typical usage: |
30 /// On the main thread: | 31 /// On the main thread: |
31 /// - Create the thread yourself (using pthreads). | 32 /// - Create the thread yourself (using pthreads). |
32 /// - Create the message loop resource. | 33 /// - Create the message loop resource. |
33 /// - Pass the message loop resource to your thread's main function. | 34 /// - Pass the message loop resource to your thread's main function. |
34 /// - Call PostWork() on the message loop to run functions on the thread. | 35 /// - Call PostWork() on the message loop to run functions on the thread. |
35 /// | 36 /// |
36 /// From the background thread's main function: | 37 /// From the background thread's main function: |
37 /// - Call AttachToCurrentThread() with the message loop resource. | 38 /// - Call AttachToCurrentThread() with the message loop resource. |
38 /// - Call Run() with the message loop resource. | 39 /// - Call Run() with the message loop resource. |
39 /// | 40 /// |
40 /// Your callacks should look like this: | 41 /// Your callbacks should look like this: |
41 /// void DoMyWork(void* user_data, int32_t status) { | 42 /// void DoMyWork(void* user_data, int32_t status) { |
42 /// if (status != PP_OK) { | 43 /// if (status != PP_OK) { |
43 /// Cleanup(); // e.g. free user_data. | 44 /// Cleanup(); // e.g. free user_data. |
44 /// return; | 45 /// return; |
45 /// } | 46 /// } |
46 /// ... do your work... | 47 /// ... do your work... |
47 /// } | 48 /// } |
48 /// For a C++ example, see ppapi/utility/threading/simple_thread.h | 49 /// For a C++ example, see ppapi/utility/threading/simple_thread.h |
49 /// | 50 /// |
50 /// (You can also create the message loop resource on the background thread, | 51 /// (You can also create the message loop resource on the background thread, |
(...skipping 141 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
192 /// to call run on the main thread's message loop (see above). | 193 /// to call run on the main thread's message loop (see above). |
193 int32_t Run(); | 194 int32_t Run(); |
194 | 195 |
195 /// Schedules work to run on the given message loop. This may be called from | 196 /// Schedules work to run on the given message loop. This may be called from |
196 /// any thread. Posted work will be executed in the order it was posted when | 197 /// any thread. Posted work will be executed in the order it was posted when |
197 /// the message loop is Run(). | 198 /// the message loop is Run(). |
198 /// | 199 /// |
199 /// @param callback A pointer to the completion callback to execute from the | 200 /// @param callback A pointer to the completion callback to execute from the |
200 /// message loop. | 201 /// message loop. |
201 /// | 202 /// |
202 /// @param delay_ms The number of millseconds to delay execution of the given | 203 /// @param delay_ms The number of milliseconds to delay execution of the given |
203 /// completion callback. Passing 0 means it will get queued normally and | 204 /// completion callback. Passing 0 means it will get queued normally and |
204 /// executed in order. | 205 /// executed in order. |
205 /// | 206 /// |
206 /// | 207 /// |
207 /// The completion callback will be called with PP_OK as the "result" | 208 /// The completion callback will be called with PP_OK as the "result" |
208 /// parameter if it is run normally. It is good practice to check for PP_OK | 209 /// parameter if it is run normally. It is good practice to check for PP_OK |
209 /// and return early otherwise. | 210 /// and return early otherwise. |
210 /// | 211 /// |
211 /// The "required" flag on the completion callback is ignored. If there is an | 212 /// The "required" flag on the completion callback is ignored. If there is an |
212 /// error posting your callback, the error will be returned from PostWork and | 213 /// error posting your callback, the error will be returned from PostWork and |
(...skipping 40 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
253 /// - PP_ERROR_BADRESOURCE: The message loop was invalid. | 254 /// - PP_ERROR_BADRESOURCE: The message loop was invalid. |
254 /// - PP_ERROR_WRONG_THREAD: You are attempting to quit the main thread. | 255 /// - PP_ERROR_WRONG_THREAD: You are attempting to quit the main thread. |
255 /// The main thread's message loop is managed by the system and can't be | 256 /// The main thread's message loop is managed by the system and can't be |
256 /// quit. | 257 /// quit. |
257 int32_t PostQuit(bool should_destroy); | 258 int32_t PostQuit(bool should_destroy); |
258 }; | 259 }; |
259 | 260 |
260 } // namespace pp | 261 } // namespace pp |
261 | 262 |
262 #endif // PPAPI_CPP_MESSAGE_LOOP_H_ | 263 #endif // PPAPI_CPP_MESSAGE_LOOP_H_ |
OLD | NEW |