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 | #ifndef PPAPI_CPP_MESSAGE_LOOP_H_ |
| 6 | #define PPAPI_CPP_MESSAGE_LOOP_H_ |
| 7 | |
| 8 | #include "ppapi/cpp/resource.h" |
| 9 | |
Torne (Richard Coles) | 868fa2f | 2013-06-11 10:57:03 +0100 | [diff] [blame] | 10 | /// @file |
| 11 | /// This file defines the PPB_MessageLoop API. |
| 12 | |
Torne (Richard Coles) | 2a99a7e | 2013-03-28 15:31:22 +0000 | [diff] [blame] | 13 | namespace pp { |
| 14 | |
| 15 | class CompletionCallback; |
| 16 | class InstanceHandle; |
| 17 | |
| 18 | /// A message loop allows PPAPI calls to be issued on a thread. You may not |
| 19 | /// issue any API calls on a thread without creating a message loop. It also |
| 20 | /// allows you to post work to the message loop for a thread. |
| 21 | /// |
| 22 | /// To process work posted to the message loop, as well as completion callbacks |
| 23 | /// for asynchronous operations, you must run the message loop via Run(). |
| 24 | /// |
| 25 | /// Note the system manages the lifetime of the instance (and all associated |
| 26 | /// resources). If the instance is deleted from the page, background threads may |
| 27 | /// suddenly see their PP_Resource handles become invalid. In this case, calls |
| 28 | /// will fail with PP_ERROR_BADRESOURCE. If you need to access data associated |
| 29 | /// 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] | 30 | /// proxy object that can handle asynchronous destruction of the instance |
| 31 | /// object. |
Torne (Richard Coles) | 2a99a7e | 2013-03-28 15:31:22 +0000 | [diff] [blame] | 32 | /// |
| 33 | /// Typical usage: |
| 34 | /// On the main thread: |
| 35 | /// - Create the thread yourself (using pthreads). |
| 36 | /// - Create the message loop resource. |
| 37 | /// - Pass the message loop resource to your thread's main function. |
| 38 | /// - Call PostWork() on the message loop to run functions on the thread. |
| 39 | /// |
| 40 | /// From the background thread's main function: |
| 41 | /// - Call AttachToCurrentThread() with the message loop resource. |
| 42 | /// - Call Run() with the message loop resource. |
| 43 | /// |
Torne (Richard Coles) | c2e0dbd | 2013-05-09 18:35:53 +0100 | [diff] [blame] | 44 | /// Your callbacks should look like this: |
Torne (Richard Coles) | 868fa2f | 2013-06-11 10:57:03 +0100 | [diff] [blame] | 45 | /// @code |
| 46 | /// void DoMyWork(void* user_data, int32_t status) { |
| 47 | /// if (status != PP_OK) { |
| 48 | /// Cleanup(); // e.g. free user_data. |
| 49 | /// return; |
| 50 | /// } |
| 51 | /// ... do your work... |
| 52 | /// } |
| 53 | /// @endcode |
Torne (Richard Coles) | 2a99a7e | 2013-03-28 15:31:22 +0000 | [diff] [blame] | 54 | /// For a C++ example, see ppapi/utility/threading/simple_thread.h |
| 55 | /// |
| 56 | /// (You can also create the message loop resource on the background thread, |
| 57 | /// but then the main thread will have no reference to it should you want to |
| 58 | /// call PostWork()). |
| 59 | /// |
| 60 | /// |
| 61 | /// THREAD HANDLING |
| 62 | /// |
| 63 | /// The main thread has an implicitly created message loop. The main thread is |
| 64 | /// the thread where PPP_InitializeModule and PPP_Instance functions are called. |
| 65 | /// You can retrieve a reference to this message loop by calling |
Torne (Richard Coles) | 5d1f7b1 | 2014-02-21 12:16:55 +0000 | [diff] [blame] | 66 | /// GetForMainThread() or, if your code is on the main thread, GetCurrent() will |
| 67 | /// also work. |
Torne (Richard Coles) | 2a99a7e | 2013-03-28 15:31:22 +0000 | [diff] [blame] | 68 | /// |
| 69 | /// Some special threads created by the system can not have message loops. In |
| 70 | /// particular, the background thread created for audio processing has this |
| 71 | /// requirement because it's intended to be highly responsive to keep up with |
| 72 | /// the realtime requirements of audio processing. You can not make PPAPI calls |
| 73 | /// from these threads. |
| 74 | /// |
| 75 | /// Once you associate a message loop with a thread, you don't have to keep a |
| 76 | /// reference to it. The system will hold a reference to the message loop for as |
| 77 | /// long as the thread is running. The current message loop can be retrieved |
| 78 | /// using the GetCurrent() function. |
| 79 | /// |
| 80 | /// It is legal to create threads in your plugin without message loops, but |
| 81 | /// PPAPI calls will fail unless explicitly noted in the documentation. |
| 82 | /// |
| 83 | /// You can create a message loop object on a thread and never actually run the |
| 84 | /// message loop. This will allow you to call blocking PPAPI calls (via |
| 85 | /// PP_BlockUntilComplete()). If you make any asynchronous calls, the callbacks |
| 86 | /// from those calls will be queued in the message loop and never run. The same |
| 87 | /// thing will happen if work is scheduled after the message loop exits and |
| 88 | /// the message loop is not run again. |
| 89 | /// |
| 90 | /// |
| 91 | /// DESTRUCTION AND ERROR HANDLING |
| 92 | /// |
| 93 | /// Often, your application will associate memory with completion callbacks. For |
| 94 | /// example, the C++ CompletionCallbackFactory has a small amount of |
| 95 | /// heap-allocated memory for each callback. This memory will be leaked if the |
| 96 | /// callback is never run. To avoid this memory leak, you need to be careful |
| 97 | /// about error handling and shutdown. |
| 98 | /// |
| 99 | /// There are a number of cases where posted callbacks will never be run: |
| 100 | /// |
| 101 | /// - You tear down the thread (via pthreads) without "destroying" the message |
| 102 | /// loop (via PostQuit with should_destroy = PP_TRUE). In this case, any |
| 103 | /// tasks in the message queue will be lost. |
| 104 | /// |
| 105 | /// - You create a message loop, post callbacks to it, and never run it. |
| 106 | /// |
| 107 | /// - You quit the message loop via PostQuit with should_destroy set to |
| 108 | /// PP_FALSE. In this case, the system will assume the message loop will be |
| 109 | /// run again later and keep your tasks. |
| 110 | /// |
| 111 | /// To do proper shutdown, call PostQuit with should_destroy = PP_TRUE. This |
| 112 | /// will prohibit future work from being posted, and will allow the message loop |
| 113 | /// to run until all pending tasks are run. |
| 114 | /// |
| 115 | /// If you post a callback to a message loop that's been destroyed, or to an |
| 116 | /// invalid message loop, PostWork will return an error and will not run the |
| 117 | /// callback. This is true even for callbacks with the "required" flag set, |
| 118 | /// since the system may not even know what thread to issue the error callback |
| 119 | /// on. |
| 120 | /// |
| 121 | /// Therefore, you should check for errors from PostWork and destroy any |
| 122 | /// associated memory to avoid leaks. If you're using the C++ |
| 123 | /// CompletionCallbackFactory, use the following pattern: |
Torne (Richard Coles) | 868fa2f | 2013-06-11 10:57:03 +0100 | [diff] [blame] | 124 | /// @code |
| 125 | /// pp::CompletionCallback callback = factory_.NewOptionalCallback(...); |
| 126 | /// int32_t result = message_loop.PostWork(callback); |
| 127 | /// if (result != PP_OK) |
| 128 | /// callback.Run(result); |
| 129 | /// @endcode |
Torne (Richard Coles) | 2a99a7e | 2013-03-28 15:31:22 +0000 | [diff] [blame] | 130 | /// This will run the callback with an error value, and assumes that the |
| 131 | /// implementation of your callback checks the "result" argument and returns |
| 132 | /// immediately on error. |
| 133 | class MessageLoop : public Resource { |
| 134 | public: |
| 135 | /// Creates an is_null() MessageLoop resource. |
| 136 | MessageLoop(); |
| 137 | |
| 138 | /// Creates a message loop associated with the given instance. The resource |
| 139 | /// will be is_null() on failure. |
| 140 | /// |
| 141 | /// This may be called from any thread. After your thread starts but before |
| 142 | /// issuing any other PPAPI calls on it, you must associate it with a message |
| 143 | /// loop by calling AttachToCurrentThread. |
| 144 | explicit MessageLoop(const InstanceHandle& instance); |
| 145 | |
| 146 | MessageLoop(const MessageLoop& other); |
| 147 | |
| 148 | /// Takes an additional ref to the resource. |
| 149 | explicit MessageLoop(PP_Resource pp_message_loop); |
| 150 | |
| 151 | static MessageLoop GetForMainThread(); |
| 152 | static MessageLoop GetCurrent(); |
| 153 | |
| 154 | /// Sets the given message loop resource as being the associated message loop |
| 155 | /// for the currently running thread. |
| 156 | /// |
| 157 | /// You must call this function exactly once on a thread before making any |
| 158 | /// PPAPI calls. A message loop can only be attached to one thread, and the |
| 159 | /// message loop can not be changed later. The message loop will be attached |
| 160 | /// as long as the thread is running or until you quit with should_destroy |
| 161 | /// set to PP_TRUE. |
| 162 | /// |
| 163 | /// If this function fails, attempting to run the message loop will fail. |
| 164 | /// Note that you can still post work to the message loop: it will get queued |
| 165 | /// up should the message loop eventually be successfully attached and run. |
| 166 | /// |
| 167 | /// @return |
| 168 | /// - PP_OK: The message loop was successfully attached to the thread and is |
| 169 | /// ready to use. |
| 170 | /// - PP_ERROR_BADRESOURCE: The given message loop resource is invalid. |
| 171 | /// - PP_ERROR_INPROGRESS: The current thread already has a message loop |
| 172 | /// attached. This will always be the case for the main thread, which has |
| 173 | /// an implicit system-created message loop attached. |
| 174 | /// - PP_ERROR_WRONG_THREAD: The current thread type can not have a message |
| 175 | /// loop attached to it. See the interface level discussion about these |
| 176 | /// special threads, which include realtime audio threads. |
| 177 | int32_t AttachToCurrentThread(); |
| 178 | |
| 179 | /// Runs the thread message loop. Running the message loop is required for |
| 180 | /// you to get issued completion callbacks on the thread. |
| 181 | /// |
| 182 | /// The message loop identified by the argument must have been previously |
| 183 | /// successfully attached to the current thread. |
| 184 | /// |
| 185 | /// You may not run nested message loops. Since the main thread has an |
| 186 | /// implicit message loop that the system runs, you may not call Run on the |
| 187 | /// main thread. |
| 188 | /// |
| 189 | /// @return |
| 190 | /// - PP_OK: The message loop was successfully run. Note that on |
| 191 | /// success, the message loop will only exit when you call PostQuit(). |
| 192 | /// - PP_ERROR_BADRESOURCE: The given message loop resource is invalid. |
| 193 | /// - PP_ERROR_WRONG_THREAD: You are attempting to run a message loop that |
| 194 | /// has not been successfully attached to the current thread. Call |
| 195 | /// AttachToCurrentThread(). |
| 196 | /// - PP_ERROR_INPROGRESS: You are attempting to call Run in a nested |
| 197 | /// fashion (Run is already on the stack). This will occur if you attempt |
| 198 | /// to call run on the main thread's message loop (see above). |
| 199 | int32_t Run(); |
| 200 | |
| 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 |
| 203 | /// the message loop is Run(). |
| 204 | /// |
| 205 | /// @param callback A pointer to the completion callback to execute from the |
| 206 | /// message loop. |
| 207 | /// |
Torne (Richard Coles) | c2e0dbd | 2013-05-09 18:35:53 +0100 | [diff] [blame] | 208 | /// @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] | 209 | /// completion callback. Passing 0 means it will get queued normally and |
| 210 | /// executed in order. |
| 211 | /// |
| 212 | /// |
| 213 | /// The completion callback will be called with PP_OK as the "result" |
| 214 | /// parameter if it is run normally. It is good practice to check for PP_OK |
| 215 | /// and return early otherwise. |
| 216 | /// |
| 217 | /// The "required" flag on the completion callback is ignored. If there is an |
| 218 | /// error posting your callback, the error will be returned from PostWork and |
| 219 | /// the callback will never be run (because there is no appropriate place to |
| 220 | /// run your callback with an error without causing unexpected threading |
| 221 | /// problems). If you associate memory with the completion callback (for |
| 222 | /// example, you're using the C++ CompletionCallbackFactory), you will need to |
| 223 | /// free this or manually run the callback. See "Desctruction and error |
| 224 | /// handling" above. |
| 225 | /// |
| 226 | /// |
| 227 | /// You can call this function before the message loop has started and the |
| 228 | /// work will get queued until the message loop is run. You can also post |
| 229 | /// work after the message loop has exited as long as should_destroy was |
| 230 | /// PP_FALSE. It will be queued until the next invocation of Run(). |
| 231 | /// |
| 232 | /// @return |
| 233 | /// - PP_OK: The work was posted to the message loop's queue. As described |
| 234 | /// above, this does not mean that the work has been or will be executed |
| 235 | /// (if you never run the message loop after posting). |
| 236 | /// - PP_ERROR_BADRESOURCE: The given message loop resource is invalid. |
| 237 | /// - PP_ERROR_BADARGUMENT: The function pointer for the completion callback |
| 238 | /// is null (this will be the case if you pass PP_BlockUntilComplete()). |
| 239 | /// - PP_ERROR_FAILED: The message loop has been destroyed. |
| 240 | int32_t PostWork(const CompletionCallback& callback, |
| 241 | int64_t delay_ms = 0); |
| 242 | |
| 243 | /// Posts a quit message to the given message loop's work queue. Work posted |
| 244 | /// before that point will be processed before quitting. |
| 245 | /// |
| 246 | /// This may be called on the message loop registered for the current thread, |
| 247 | /// or it may be called on the message loop registered for another thread. It |
| 248 | /// is an error to attempt to quit the main thread loop. |
| 249 | /// |
| 250 | /// @param should_destroy Marks the message loop as being in a destroyed |
| 251 | /// state and prevents further posting of messages. |
| 252 | /// |
| 253 | /// If you quit a message loop without setting should_destroy, it will still |
| 254 | /// be attached to the thread and you can still run it again by calling Run() |
| 255 | /// again. If you destroy it, it will be detached from the current thread. |
| 256 | /// |
| 257 | /// @return |
| 258 | /// - PP_OK: The request to quit was successfully posted. |
| 259 | /// - PP_ERROR_BADRESOURCE: The message loop was invalid. |
| 260 | /// - PP_ERROR_WRONG_THREAD: You are attempting to quit the main thread. |
| 261 | /// The main thread's message loop is managed by the system and can't be |
| 262 | /// quit. |
| 263 | int32_t PostQuit(bool should_destroy); |
| 264 | }; |
| 265 | |
| 266 | } // namespace pp |
| 267 | |
| 268 | #endif // PPAPI_CPP_MESSAGE_LOOP_H_ |