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