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