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 | 5 |
6 /** | 6 /** |
7 * This file defines the API to create and run a callback. | 7 * This file defines the API to create and run a callback. |
8 */ | 8 */ |
9 | 9 |
10 /** | 10 /** |
(...skipping 48 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
59 }; | 59 }; |
60 | 60 |
61 | 61 |
62 /** | 62 /** |
63 * <code>PP_CompletionCallback</code> is a common mechanism for supporting | 63 * <code>PP_CompletionCallback</code> is a common mechanism for supporting |
64 * potentially asynchronous calls in browser interfaces. Any method that takes a | 64 * potentially asynchronous calls in browser interfaces. Any method that takes a |
65 * <code>PP_CompletionCallback</code> can be used in one of three different | 65 * <code>PP_CompletionCallback</code> can be used in one of three different |
66 * ways: | 66 * ways: |
67 * - Required: The callback will always be invoked asynchronously on the | 67 * - Required: The callback will always be invoked asynchronously on the |
68 * thread where the associated PPB method was invoked. The method | 68 * thread where the associated PPB method was invoked. The method |
69 * will always return <code>PP_OK_COMPLETIONPENDING</code> when a | 69 * will always return PP_OK_COMPLETIONPENDING when a required |
70 * required callback, and the callback will be invoked later | 70 * callback, and the callback will be invoked later (barring |
71 * (barring system or thread shutdown; see PPB_MessageLoop for | 71 * system or thread shutdown; see PPB_MessageLoop for details). |
72 * details). Required callbacks are the default. | 72 * Required callbacks are the default. |
73 * | 73 * |
74 * NOTE: If you use a required callback on a background thread, | 74 * NOTE: If you use a required callback on a background thread, |
75 * you must have created and attached a PPB_MessageLoop. | 75 * you must have created and attached a PPB_MessageLoop. |
76 * Otherwise, the system can not run your callback on that thread, | 76 * Otherwise, the system can not run your callback on that thread, |
77 * and will instead emit a log message and crash your plugin to | 77 * and will instead emit a log message and crash your plugin to |
78 * make the problem more obvious. | 78 * make the problem more obvious. |
79 * | 79 * |
80 * - Optional: The callback may be invoked asynchronously, or the PPB method | 80 * - Optional: The callback may be invoked asynchronously, or the PPB method |
81 * may complete synchronously if it can do so without blocking. | 81 * may complete synchronously if it can do so without blocking. |
82 * If the method will complete asynchronously, it will return | 82 * If the method will complete asynchronously, it will return |
(...skipping 51 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
134 /** | 134 /** |
135 * @addtogroup Functions | 135 * @addtogroup Functions |
136 * @{ | 136 * @{ |
137 */ | 137 */ |
138 /** | 138 /** |
139 * PP_MakeCompletionCallback() is used to create a | 139 * PP_MakeCompletionCallback() is used to create a |
140 * <code>PP_CompletionCallback</code>. | 140 * <code>PP_CompletionCallback</code>. |
141 * | 141 * |
142 * <strong>Example, creating a Required callback:</strong> | 142 * <strong>Example, creating a Required callback:</strong> |
143 * | 143 * |
144 * <code> | 144 * @code |
145 * struct PP_CompletionCallback cc = PP_MakeCompletionCallback(Foo, NULL); | 145 * struct PP_CompletionCallback cc = PP_MakeCompletionCallback(Foo, NULL); |
146 * </code> | 146 * @endcode |
147 * | 147 * |
148 * <strong>Example, creating an Optional callback:</strong> | 148 * <strong>Example, creating an Optional callback:</strong> |
149 * | 149 * |
150 * <code> | 150 * @code |
151 * struct PP_CompletionCallback cc = PP_MakeCompletionCallback(Foo, NULL); | 151 * struct PP_CompletionCallback cc = PP_MakeCompletionCallback(Foo, NULL); |
152 * cc.flags = cc.flags | PP_COMPLETIONCALLBACK_FLAG_OPTIONAL; | 152 * cc.flags = cc.flags | PP_COMPLETIONCALLBACK_FLAG_OPTIONAL; |
153 * </code> | 153 * @endcode |
154 * | 154 * |
155 * @param[in] func A <code>PP_CompletionCallback_Func</code> that will be | 155 * @param[in] func A <code>PP_CompletionCallback_Func</code> that will be |
156 * called. | 156 * called. |
157 * @param[in] user_data A pointer to user data passed to your callback | 157 * @param[in] user_data A pointer to user data passed to your callback |
158 * function. This is optional and is typically used to help track state | 158 * function. This is optional and is typically used to help track state |
159 * when you may have multiple callbacks pending. | 159 * when you may have multiple callbacks pending. |
160 * | 160 * |
161 * @return A <code>PP_CompletionCallback</code> structure. | 161 * @return A <code>PP_CompletionCallback</code> structure. |
162 */ | 162 */ |
163 PP_INLINE struct PP_CompletionCallback PP_MakeCompletionCallback( | 163 PP_INLINE struct PP_CompletionCallback PP_MakeCompletionCallback( |
(...skipping 89 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
253 struct PP_CompletionCallback temp = *cc; | 253 struct PP_CompletionCallback temp = *cc; |
254 *cc = PP_BlockUntilComplete(); | 254 *cc = PP_BlockUntilComplete(); |
255 PP_RunCompletionCallback(&temp, res); | 255 PP_RunCompletionCallback(&temp, res); |
256 } | 256 } |
257 /** | 257 /** |
258 * @} | 258 * @} |
259 */ | 259 */ |
260 | 260 |
261 #endinl | 261 #endinl |
262 | 262 |
OLD | NEW |