| 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 |