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 10 /// @file 11 /// This file defines the PPB_MessageLoop API. 12 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 30 /// proxy object that can handle asynchronous destruction of the instance 31 /// object. 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 /// 44 /// Your callbacks should look like this: 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 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 66 /// GetForMainThread() or, if your code is on the main thread, GetCurrent() will 67 /// also work. 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: 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 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 /// 208 /// @param delay_ms The number of milliseconds to delay execution of the given 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_ 269