| 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 |