Pepper_31_C++_interfaces
completion_callback.h
Go to the documentation of this file.
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/extensions/ext_output_traits.h"
11 #include "ppapi/cpp/logging.h"
12 #include "ppapi/cpp/module.h"
13 #include "ppapi/cpp/output_traits.h"
14 
15 /// @file
16 /// This file defines the API to create and run a callback.
17 namespace pp {
18 
19 /// This API enables you to implement and receive callbacks when
20 /// Pepper operations complete asynchronously.
21 ///
22 /// You can create these objects yourself, but it is most common to use the
23 /// CompletionCallbackFactory to allow the callbacks to call class member
24 /// functions.
26  public:
27  /// The default constructor will create a blocking
28  /// <code>CompletionCallback</code> that can be passed to a method to
29  /// indicate that the calling thread should be blocked until the asynchronous
30  /// operation corresponding to the method completes.
31  ///
32  /// <strong>Note:</strong> Blocking completion callbacks are only allowed from
33  /// from background threads.
35  cc_ = PP_BlockUntilComplete();
36  }
37 
38  /// A constructor for creating a <code>CompletionCallback</code>.
39  ///
40  /// @param[in] func The function to be called on completion.
41  /// @param[in] user_data The user data to be passed to the callback function.
42  /// This is optional and is typically used to help track state in case of
43  /// multiple pending callbacks.
44  CompletionCallback(PP_CompletionCallback_Func func, void* user_data) {
45  cc_ = PP_MakeCompletionCallback(func, user_data);
46  }
47 
48  /// A constructor for creating a <code>CompletionCallback</code> with
49  /// specified flags.
50  ///
51  /// @param[in] func The function to be called on completion.
52  /// @param[in] user_data The user data to be passed to the callback function.
53  /// This is optional and is typically used to help track state in case of
54  /// multiple pending callbacks.
55  /// @param[in] flags Bit field combination of
56  /// <code>PP_CompletionCallback_Flag</code> flags used to control how
57  /// non-NULL callbacks are scheduled by asynchronous methods.
58  CompletionCallback(PP_CompletionCallback_Func func, void* user_data,
59  int32_t flags) {
60  cc_ = PP_MakeCompletionCallback(func, user_data);
61  cc_.flags = flags;
62  }
63 
64  /// The set_flags() function is used to set the flags used to control
65  /// how non-NULL callbacks are scheduled by asynchronous methods.
66  ///
67  /// @param[in] flags Bit field combination of
68  /// <code>PP_CompletionCallback_Flag</code> flags used to control how
69  /// non-NULL callbacks are scheduled by asynchronous methods.
70  void set_flags(int32_t flags) { cc_.flags = flags; }
71 
72  /// Run() is used to run the <code>CompletionCallback</code>.
73  /// Normally, the system runs a <code>CompletionCallback</code> after an
74  /// asynchronous operation completes, but programs may wish to run the
75  /// <code>CompletionCallback</code> manually in order to reuse the same code
76  /// paths.
77  ///
78  /// @param[in] result The result of the operation to be passed to the
79  /// callback function. Non-positive values correspond to the error codes
80  /// from <code>pp_errors.h</code> (excluding
81  /// <code>PP_OK_COMPLETIONPENDING</code>). Positive values indicate
82  /// additional information such as bytes read.
83  void Run(int32_t result) {
84  PP_DCHECK(cc_.func);
85  PP_RunCompletionCallback(&cc_, result);
86  }
87 
88  /// RunAndClear() is used to run the <code>CompletionCallback</code> and
89  /// clear out the callback so that it cannot be run a second time.
90  ///
91  /// @param[in] result The result of the operation to be passed to the
92  /// callback function. Non-positive values correspond to the error codes
93  /// from <code>pp_errors.h</code> (excluding
94  /// <code>PP_OK_COMPLETIONPENDING</code>). Positive values indicate
95  /// additional information such as bytes read.
96  void RunAndClear(int32_t result) {
97  PP_DCHECK(cc_.func);
98  PP_RunAndClearCompletionCallback(&cc_, result);
99  }
100 
101  /// IsOptional() is used to determine the setting of the
102  /// <code>PP_COMPLETIONCALLBACK_FLAG_OPTIONAL</code> flag. This flag allows
103  /// any method taking such callback to complete synchronously
104  /// and not call the callback if the operation would not block. This is useful
105  /// when performance is an issue, and the operation bandwidth should not be
106  /// limited to the processing speed of the message loop.
107  ///
108  /// On synchronous method completion, the completion result will be returned
109  /// by the method itself. Otherwise, the method will return
110  /// PP_OK_COMPLETIONPENDING, and the callback will be invoked asynchronously
111  /// on the same thread where the PPB method was invoked.
112  ///
113  /// @return true if this callback is optional, otherwise false.
114  bool IsOptional() const {
115  return (cc_.func == NULL ||
116  (cc_.flags & PP_COMPLETIONCALLBACK_FLAG_OPTIONAL) != 0);
117  }
118 
119  /// The pp_completion_callback() function returns the underlying
120  /// <code>PP_CompletionCallback</code>
121  ///
122  /// @return A <code>PP_CompletionCallback</code>.
123  const PP_CompletionCallback& pp_completion_callback() const { return cc_; }
124 
125  /// The flags() function returns flags used to control how non-NULL callbacks
126  /// are scheduled by asynchronous methods.
127  ///
128  /// @return An int32_t containing a bit field combination of
129  /// <code>PP_CompletionCallback_Flag</code> flags.
130  int32_t flags() const { return cc_.flags; }
131 
132  /// MayForce() is used when implementing functions taking callbacks.
133  /// If the callback is required and <code>result</code> indicates that it has
134  /// not been scheduled, it will be forced on the main thread.
135  ///
136  /// <strong>Example:</strong>
137  ///
138  /// @code
139  ///
140  /// int32_t OpenURL(pp::URLLoader* loader,
141  /// pp::URLRequestInfo* url_request_info,
142  /// const CompletionCallback& cc) {
143  /// if (loader == NULL || url_request_info == NULL)
144  /// return cc.MayForce(PP_ERROR_BADRESOURCE);
145  /// return loader->Open(*loader, *url_request_info, cc);
146  /// }
147  ///
148  /// @endcode
149  ///
150  /// @param[in] result PP_OK_COMPLETIONPENDING or the result of the completed
151  /// operation to be passed to the callback function. PP_OK_COMPLETIONPENDING
152  /// indicates that the callback has already been scheduled. Other
153  /// non-positive values correspond to error codes from
154  /// <code>pp_errors.h</code>. Positive values indicate additional information
155  /// such as bytes read.
156  ///
157  /// @return <code>PP_OK_COMPLETIONPENDING</code> if the callback has been
158  /// forced, result parameter otherwise.
159  int32_t MayForce(int32_t result) const {
160  if (result == PP_OK_COMPLETIONPENDING || IsOptional())
161  return result;
162  // FIXME(dmichael): Use pp::MessageLoop here once it's out of Dev.
163  Module::Get()->core()->CallOnMainThread(0, *this, result);
164  return PP_OK_COMPLETIONPENDING;
165  }
166 
167  protected:
168  PP_CompletionCallback cc_;
169 };
170 
171 namespace internal {
172 
173 /// The base class of [Ext]CompletionCallbackWithOutput.
174 ///
175 /// The template parameter Traits determines the storage type
176 /// (OutputStorageType), the output parameter type used by the browser
177 /// (APIArgType), and how to map OutputStorageType to APIArgType.
178 template <typename T, typename Traits>
180  public:
181  typedef typename Traits::StorageType OutputStorageType;
182  typedef typename Traits::APIArgType APIArgType;
183  typedef Traits TraitsType;
184 
186  : CompletionCallback(),
187  output_(output) {
188  }
189 
190  CompletionCallbackWithOutputBase(PP_CompletionCallback_Func func,
191  void* user_data,
193  : CompletionCallback(func, user_data),
194  output_(output) {
195  }
196 
197  CompletionCallbackWithOutputBase(PP_CompletionCallback_Func func,
198  void* user_data,
199  int32_t flags,
201  : CompletionCallback(func, user_data, flags),
202  output_(output) {
203  }
204 
205  APIArgType output() const {
206  return Traits::StorageToAPIArg(*output_);
207  }
208 
209  private:
210  OutputStorageType* output_;
211 };
212 
213 } // namespace internal
214 
215 /// A CompletionCallbackWithOutput defines a completion callback that
216 /// additionally stores a pointer to some output data. Some C++ wrappers
217 /// take a CompletionCallbackWithOutput when the browser is returning a
218 /// bit of data as part of the function call. The "output" parameter
219 /// stored in the CompletionCallbackWithOutput will receive the data from
220 /// the browser.
221 ///
222 /// You can create this yourself, but it is most common to use with the
223 /// CompletionCallbackFactory's NewCallbackWithOutput, which manages the
224 /// storage for the output parameter for you and passes it as an argument
225 /// to your callback function.
226 ///
227 /// Note that this class doesn't actually do anything with the output data,
228 /// it just stores a pointer to it. C++ wrapper objects that accept a
229 /// CompletionCallbackWithOutput will retrieve this pointer and pass it to
230 /// the browser as the output parameter.
231 template <typename T>
234  T, internal::CallbackOutputTraits<T> > {
235  public:
238 
239  /// The default constructor will create a blocking
240  /// <code>CompletionCallbackWithOutput</code> that references the given output
241  /// data.
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  /// In the common case, <code>OutputStorageType</code> will be equal to the
246  /// template parameter T (for example,
247  /// <code>CompletionCallbackWithOutput<int></code> would obviously take an
248  /// int*. However, resources are passed as PP_Resource, vars as PP_Var, and
249  /// arrays as our special ArrayOutputAdapter object.
250  /// <code>internal::CallbackOutputTraits</code> defines specializations for
251  /// all of these cases.
252  ///
253  /// <strong>Note:</strong> Blocking completion callbacks are only allowed from
254  /// background threads.
256  typename BaseType::OutputStorageType* output)
257  : BaseType(output) {
258  }
259 
260  /// A constructor for creating a <code>CompletionCallbackWithOutput</code>
261  /// that references the given output data.
262  ///
263  /// @param[in] func The function to be called on completion.
264  /// @param[in] user_data The user data to be passed to the callback function.
265  /// This is optional and is typically used to help track state in case of
266  /// multiple pending callbacks.
267  /// @param[in] output A pointer to the data associated with the callback. The
268  /// caller must ensure that this pointer outlives the completion callback.
269  CompletionCallbackWithOutput(PP_CompletionCallback_Func func,
270  void* user_data,
271  typename BaseType::OutputStorageType* output)
272  : BaseType(func, user_data, output) {
273  }
274 
275  /// A constructor for creating a <code>CompletionCallbackWithOutput</code>
276  /// that references the given output data.
277  ///
278  /// @param[in] func The function to be called on completion.
279  ///
280  /// @param[in] user_data The user data to be passed to the callback function.
281  /// This is optional and is typically used to help track state in case of
282  /// multiple pending callbacks.
283  ///
284  /// @param[in] flags Bit field combination of
285  /// <code>PP_CompletionCallback_Flag</code> flags used to control how
286  /// non-NULL callbacks are scheduled by asynchronous methods.
287  ///
288  /// @param[in] output A pointer to the data associated with the callback. The
289  /// caller must ensure that this pointer outlives the completion callback.
290  CompletionCallbackWithOutput(PP_CompletionCallback_Func func,
291  void* user_data,
292  int32_t flags,
293  typename BaseType::OutputStorageType* output)
294  : BaseType(func, user_data, flags, output) {
295  }
296 };
297 
298 namespace ext {
299 
300 /// ExtCompletionCallbackWithOutput is similar to CompletionCallbackWithOutput,
301 /// but used by APIs within the pp::ext namespace. Usually it is used with the
302 /// CompletionCallbackFactory's NewExtCallbackWithOutput.
303 template <typename T>
306  T, internal::ExtCallbackOutputTraits<T> > {
307  public:
308  typedef ::pp::internal::CompletionCallbackWithOutputBase<
310 
311  /// The default constructor will create a blocking
312  /// <code>ExtCompletionCallbackWithOutput</code> that references the given
313  /// output data.
314  ///
315  /// @param[in] output A pointer to the data associated with the callback. The
316  /// caller must ensure that this pointer outlives the completion callback.
317  /// <code>OutputStorageType</code> is either
318  /// <code>ext::internal::ArrayVarOutputAdapterWithStorage<U></code> (if the
319  /// template parameter T is of the form std::vector<U>) or
320  /// <code>ext::internal::VarOutputAdapterWithStorage<T></code> (otherwise).
321  ///
322  /// <strong>Note:</strong> Blocking completion callbacks are only allowed from
323  /// background threads.
326  : BaseType(output) {
327  }
328 
329  /// A constructor for creating an <code>ExtCompletionCallbackWithOutput</code>
330  /// that references the given output data.
331  ///
332  /// @param[in] func The function to be called on completion.
333  /// @param[in] user_data The user data to be passed to the callback function.
334  /// This is optional and is typically used to help track state in case of
335  /// multiple pending callbacks.
336  /// @param[in] output A pointer to the data associated with the callback. The
337  /// caller must ensure that this pointer outlives the completion callback.
338  ExtCompletionCallbackWithOutput(PP_CompletionCallback_Func func,
339  void* user_data,
341  : BaseType(func, user_data, output) {
342  }
343 
344  /// A constructor for creating an <code>ExtCompletionCallbackWithOutput</code>
345  /// that references the given output data.
346  ///
347  /// @param[in] func The function to be called on completion.
348  ///
349  /// @param[in] user_data The user data to be passed to the callback function.
350  /// This is optional and is typically used to help track state in case of
351  /// multiple pending callbacks.
352  ///
353  /// @param[in] flags Bit field combination of
354  /// <code>PP_CompletionCallback_Flag</code> flags used to control how
355  /// non-NULL callbacks are scheduled by asynchronous methods.
356  ///
357  /// @param[in] output A pointer to the data associated with the callback. The
358  /// caller must ensure that this pointer outlives the completion callback.
359  ExtCompletionCallbackWithOutput(PP_CompletionCallback_Func func,
360  void* user_data,
361  int32_t flags,
363  : BaseType(func, user_data, flags, output) {
364  }
365 };
366 
367 } // namespace ext
368 
369 /// BlockUntilComplete() is used in place of an actual completion callback
370 /// to request blocking behavior. If specified, the calling thread will block
371 /// until the function completes. Blocking completion callbacks are only
372 /// allowed from background threads.
373 ///
374 /// @return A <code>CompletionCallback</code> corresponding to a NULL callback.
376  // Note: Explicitly inlined to avoid link errors when included into
377  // ppapi_proxy and ppapi_cpp_objects.
378  return CompletionCallback();
379 }
380 
381 } // namespace pp
382 
383 #endif // PPAPI_CPP_COMPLETION_CALLBACK_H_
void RunAndClear(int32_t result)
::pp::internal::CompletionCallbackWithOutputBase< T, internal::ExtCallbackOutputTraits< T > > BaseType
ExtCompletionCallbackWithOutput(typename BaseType::OutputStorageType *output)
Core * core()
Definition: module.h:74
#define PP_DCHECK(a)
Definition: logging.h:16
static Module * Get()
int32_t MayForce(int32_t result) const
CompletionCallbackWithOutputBase(OutputStorageType *output)
const PP_CompletionCallback & pp_completion_callback() const
ExtCompletionCallbackWithOutput(PP_CompletionCallback_Func func, void *user_data, int32_t flags, typename BaseType::OutputStorageType *output)
ExtCompletionCallbackWithOutput(PP_CompletionCallback_Func func, void *user_data, typename BaseType::OutputStorageType *output)
CompletionCallbackWithOutputBase(PP_CompletionCallback_Func func, void *user_data, int32_t flags, OutputStorageType *output)
PP_CompletionCallback cc_
void CallOnMainThread(int32_t delay_in_milliseconds, const CompletionCallback &callback, int32_t result=0)
CompletionCallback BlockUntilComplete()
CompletionCallbackWithOutputBase(PP_CompletionCallback_Func func, void *user_data, OutputStorageType *output)
CompletionCallback(PP_CompletionCallback_Func func, void *user_data, int32_t flags)
void set_flags(int32_t flags)
void Run(int32_t result)
CompletionCallback(PP_CompletionCallback_Func func, void *user_data)