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_COMPLETION_CALLBACK_H_ 6 #define PPAPI_CPP_COMPLETION_CALLBACK_H_ 7 8 #include "ppapi/c/pp_completion_callback.h" 9 #include "ppapi/c/pp_errors.h" 10 #include "ppapi/cpp/logging.h" 11 #include "ppapi/cpp/module.h" 12 #include "ppapi/cpp/output_traits.h" 13 14 /// @file 15 /// This file defines the API to create and run a callback. 16 namespace pp { 17 18 /// This API enables you to implement and receive callbacks when 19 /// Pepper operations complete asynchronously. 20 /// 21 /// You can create these objects yourself, but it is most common to use the 22 /// CompletionCallbackFactory to allow the callbacks to call class member 23 /// functions. 24 class CompletionCallback { 25 public: 26 /// The default constructor will create a blocking 27 /// <code>CompletionCallback</code> that can be passed to a method to 28 /// indicate that the calling thread should be blocked until the asynchronous 29 /// operation corresponding to the method completes. 30 /// 31 /// <strong>Note:</strong> Blocking completion callbacks are only allowed from 32 /// from background threads. 33 CompletionCallback() { 34 cc_ = PP_BlockUntilComplete(); 35 } 36 37 /// A constructor for creating a <code>CompletionCallback</code>. 38 /// 39 /// @param[in] func The function to be called on completion. 40 /// @param[in] user_data The user data to be passed to the callback function. 41 /// This is optional and is typically used to help track state in case of 42 /// multiple pending callbacks. 43 CompletionCallback(PP_CompletionCallback_Func func, void* user_data) { 44 cc_ = PP_MakeCompletionCallback(func, user_data); 45 } 46 47 /// A constructor for creating a <code>CompletionCallback</code> with 48 /// specified flags. 49 /// 50 /// @param[in] func The function to be called on completion. 51 /// @param[in] user_data The user data to be passed to the callback function. 52 /// This is optional and is typically used to help track state in case of 53 /// multiple pending callbacks. 54 /// @param[in] flags Bit field combination of 55 /// <code>PP_CompletionCallback_Flag</code> flags used to control how 56 /// non-NULL callbacks are scheduled by asynchronous methods. 57 CompletionCallback(PP_CompletionCallback_Func func, void* user_data, 58 int32_t flags) { 59 cc_ = PP_MakeCompletionCallback(func, user_data); 60 cc_.flags = flags; 61 } 62 63 /// The set_flags() function is used to set the flags used to control 64 /// how non-NULL callbacks are scheduled by asynchronous methods. 65 /// 66 /// @param[in] flags Bit field combination of 67 /// <code>PP_CompletionCallback_Flag</code> flags used to control how 68 /// non-NULL callbacks are scheduled by asynchronous methods. 69 void set_flags(int32_t flags) { cc_.flags = flags; } 70 71 /// Run() is used to run the <code>CompletionCallback</code>. 72 /// Normally, the system runs a <code>CompletionCallback</code> after an 73 /// asynchronous operation completes, but programs may wish to run the 74 /// <code>CompletionCallback</code> manually in order to reuse the same code 75 /// paths. 76 /// 77 /// @param[in] result The result of the operation to be passed to the 78 /// callback function. Non-positive values correspond to the error codes 79 /// from <code>pp_errors.h</code> (excluding 80 /// <code>PP_OK_COMPLETIONPENDING</code>). Positive values indicate 81 /// additional information such as bytes read. 82 void Run(int32_t result) { 83 PP_DCHECK(cc_.func); 84 PP_RunCompletionCallback(&cc_, result); 85 } 86 87 /// RunAndClear() is used to run the <code>CompletionCallback</code> and 88 /// clear out the callback so that it cannot be run a second time. 89 /// 90 /// @param[in] result The result of the operation to be passed to the 91 /// callback function. Non-positive values correspond to the error codes 92 /// from <code>pp_errors.h</code> (excluding 93 /// <code>PP_OK_COMPLETIONPENDING</code>). Positive values indicate 94 /// additional information such as bytes read. 95 void RunAndClear(int32_t result) { 96 PP_DCHECK(cc_.func); 97 PP_RunAndClearCompletionCallback(&cc_, result); 98 } 99 100 /// IsOptional() is used to determine the setting of the 101 /// <code>PP_COMPLETIONCALLBACK_FLAG_OPTIONAL</code> flag. This flag allows 102 /// any method taking such callback to complete synchronously 103 /// and not call the callback if the operation would not block. This is useful 104 /// when performance is an issue, and the operation bandwidth should not be 105 /// limited to the processing speed of the message loop. 106 /// 107 /// On synchronous method completion, the completion result will be returned 108 /// by the method itself. Otherwise, the method will return 109 /// PP_OK_COMPLETIONPENDING, and the callback will be invoked asynchronously 110 /// on the same thread where the PPB method was invoked. 111 /// 112 /// @return true if this callback is optional, otherwise false. 113 bool IsOptional() const { 114 return (cc_.func == NULL || 115 (cc_.flags & PP_COMPLETIONCALLBACK_FLAG_OPTIONAL) != 0); 116 } 117 118 /// The pp_completion_callback() function returns the underlying 119 /// <code>PP_CompletionCallback</code> 120 /// 121 /// @return A <code>PP_CompletionCallback</code>. 122 const PP_CompletionCallback& pp_completion_callback() const { return cc_; } 123 124 /// The flags() function returns flags used to control how non-NULL callbacks 125 /// are scheduled by asynchronous methods. 126 /// 127 /// @return An int32_t containing a bit field combination of 128 /// <code>PP_CompletionCallback_Flag</code> flags. 129 int32_t flags() const { return cc_.flags; } 130 131 /// MayForce() is used when implementing functions taking callbacks. 132 /// If the callback is required and <code>result</code> indicates that it has 133 /// not been scheduled, it will be forced on the main thread. 134 /// 135 /// <strong>Example:</strong> 136 /// 137 /// @code 138 /// 139 /// int32_t OpenURL(pp::URLLoader* loader, 140 /// pp::URLRequestInfo* url_request_info, 141 /// const CompletionCallback& cc) { 142 /// if (loader == NULL || url_request_info == NULL) 143 /// return cc.MayForce(PP_ERROR_BADRESOURCE); 144 /// return loader->Open(*loader, *url_request_info, cc); 145 /// } 146 /// 147 /// @endcode 148 /// 149 /// @param[in] result PP_OK_COMPLETIONPENDING or the result of the completed 150 /// operation to be passed to the callback function. PP_OK_COMPLETIONPENDING 151 /// indicates that the callback has already been scheduled. Other 152 /// non-positive values correspond to error codes from 153 /// <code>pp_errors.h</code>. Positive values indicate additional information 154 /// such as bytes read. 155 /// 156 /// @return <code>PP_OK_COMPLETIONPENDING</code> if the callback has been 157 /// forced, result parameter otherwise. 158 int32_t MayForce(int32_t result) const { 159 if (result == PP_OK_COMPLETIONPENDING || IsOptional()) 160 return result; 161 // FIXME(dmichael): Use pp::MessageLoop here once it's out of Dev. 162 Module::Get()->core()->CallOnMainThread(0, *this, result); 163 return PP_OK_COMPLETIONPENDING; 164 } 165 166 protected: 167 PP_CompletionCallback cc_; 168 }; 169 170 /// A CompletionCallbackWithOutput defines a completion callback that 171 /// additionally stores a pointer to some output data. Some C++ wrappers 172 /// take a CompletionCallbackWithOutput when the browser is returning a 173 /// bit of data as part of the function call. The "output" parameter 174 /// stored in the CompletionCallbackWithOutput will receive the data from 175 /// the browser. 176 /// 177 /// You can create this yourself, but it is most common to use with the 178 /// CompletionCallbackFactory's NewCallbackWithOutput, which manages the 179 /// storage for the output parameter for you and passes it as an argument 180 /// to your callback function. 181 /// 182 /// Note that this class doesn't actually do anything with the output data, 183 /// it just stores a pointer to it. C++ wrapper objects that accept a 184 /// CompletionCallbackWithOutput will retrieve this pointer and pass it to 185 /// the browser as the output parameter. 186 template<typename T> 187 class CompletionCallbackWithOutput : public CompletionCallback { 188 public: 189 /// The type that will actually be stored in the completion callback. In the 190 /// common case, this will be equal to the template parameter (for example, 191 /// CompletionCallbackWithOutput<int> would obviously take an int*. However, 192 /// resources are passed as PP_Resource, vars as PP_Var, and arrays as our 193 /// special ArrayOutputAdapter object. The CallbackOutputTraits defines 194 /// specializations for all of these cases. 195 typedef typename internal::CallbackOutputTraits<T>::StorageType 196 OutputStorageType; 197 typedef typename internal::CallbackOutputTraits<T>::APIArgType 198 APIArgType; 199 200 /// The default constructor will create a blocking 201 /// <code>CompletionCallback</code> that references the given output 202 /// data. 203 /// 204 /// @param[in] output A pointer to the data associated with the callback. The 205 /// caller must ensure that this pointer outlives the completion callback. 206 /// 207 /// <strong>Note:</strong> Blocking completion callbacks are only allowed from 208 /// from background threads. 209 CompletionCallbackWithOutput(OutputStorageType* output) 210 : CompletionCallback(), 211 output_(output) { 212 } 213 214 /// A constructor for creating a <code>CompletionCallback</code> that 215 /// references the given output data. 216 /// 217 /// @param[in] func The function to be called on completion. 218 /// @param[in] user_data The user data to be passed to the callback function. 219 /// This is optional and is typically used to help track state in case of 220 /// multiple pending callbacks. 221 /// @param[in] output A pointer to the data associated with the callback. The 222 /// caller must ensure that this pointer outlives the completion callback. 223 CompletionCallbackWithOutput(PP_CompletionCallback_Func func, 224 void* user_data, 225 OutputStorageType* output) 226 : CompletionCallback(func, user_data), 227 output_(output) { 228 } 229 230 /// A constructor for creating a <code>CompletionCallback</code> that 231 /// references the given output data. 232 /// 233 /// @param[in] func The function to be called on completion. 234 /// 235 /// @param[in] user_data The user data to be passed to the callback function. 236 /// This is optional and is typically used to help track state in case of 237 /// multiple pending callbacks. 238 /// 239 /// @param[in] flags Bit field combination of 240 /// <code>PP_CompletionCallback_Flag</code> flags used to control how 241 /// non-NULL callbacks are scheduled by asynchronous methods. 242 /// 243 /// @param[in] output A pointer to the data associated with the callback. The 244 /// caller must ensure that this pointer outlives the completion callback. 245 CompletionCallbackWithOutput(PP_CompletionCallback_Func func, 246 void* user_data, 247 int32_t flags, 248 OutputStorageType* output) 249 : CompletionCallback(func, user_data, flags), 250 output_(output) { 251 } 252 253 APIArgType output() const { 254 return internal::CallbackOutputTraits<T>::StorageToAPIArg(*output_); 255 } 256 257 private: 258 OutputStorageType* output_; 259 }; 260 261 /// BlockUntilComplete() is used in place of an actual completion callback 262 /// to request blocking behavior. If specified, the calling thread will block 263 /// until the function completes. Blocking completion callbacks are only 264 /// allowed from background threads. 265 /// 266 /// @return A <code>CompletionCallback</code> corresponding to a NULL callback. 267 inline CompletionCallback BlockUntilComplete() { 268 // Note: Explicitly inlined to avoid link errors when included into 269 // ppapi_proxy and ppapi_cpp_objects. 270 return CompletionCallback(); 271 } 272 273 } // namespace pp 274 275 #endif // PPAPI_CPP_COMPLETION_CALLBACK_H_ 276
