Native Client

pp::CompletionCallbackFactory< T, ThreadTraits > Class Template Reference

CompletionCallbackFactory may be used to create CompletionCallback objects that are bound to member functions. More...

List of all members.

Classes

class  BackPointer
class  CallbackData
class  Dispatcher0
class  Dispatcher1
class  Dispatcher2
class  Dispatcher3
class  DispatcherWithOutput0
class  DispatcherWithOutput1
class  DispatcherWithOutput2
class  DispatcherWithOutput3

Public Functions

 CompletionCallbackFactory (T *object=NULL)
 ~CompletionCallbackFactory ()
void CancelAll ()
void Initialize (T *object)
T * GetObject ()
template
CompletionCallback NewCallback (Method method)
template
CompletionCallback NewOptionalCallback (Method method)
template
CompletionCallbackWithOutput
< typename
internal::TypeUnwrapper
< Output >::StorageType > 
NewCallbackWithOutput (void(T::*method)(int32_t, Output))
template
ext::ExtCompletionCallbackWithOutput
< typename
internal::TypeUnwrapper
< Output >::StorageType > 
NewExtCallbackWithOutput (void(T::*method)(int32_t, Output))
template
CompletionCallback NewCallback (Method method, const A &a)
template
CompletionCallback NewOptionalCallback (Method method, const A &a)
template
CompletionCallbackWithOutput
< typename
internal::TypeUnwrapper
< Output >::StorageType > 
NewCallbackWithOutput (void(T::*method)(int32_t, Output, A), const A &a)
template
ext::ExtCompletionCallbackWithOutput
< typename
internal::TypeUnwrapper
< Output >::StorageType > 
NewExtCallbackWithOutput (void(T::*method)(int32_t, Output, A), const A &a)
template
CompletionCallback NewCallback (Method method, const A &a, const B &b)
template
CompletionCallback NewOptionalCallback (Method method, const A &a, const B &b)
template
CompletionCallbackWithOutput
< typename
internal::TypeUnwrapper
< Output >::StorageType > 
NewCallbackWithOutput (void(T::*method)(int32_t, Output, A, B), const A &a, const B &b)
template
ext::ExtCompletionCallbackWithOutput
< typename
internal::TypeUnwrapper
< Output >::StorageType > 
NewExtCallbackWithOutput (void(T::*method)(int32_t, Output, A, B), const A &a, const B &b)
template
CompletionCallback NewCallback (Method method, const A &a, const B &b, const C &c)
template
CompletionCallback NewOptionalCallback (Method method, const A &a, const B &b, const C &c)
template
CompletionCallbackWithOutput
< typename
internal::TypeUnwrapper
< Output >::StorageType > 
NewCallbackWithOutput (void(T::*method)(int32_t, Output, A, B, C), const A &a, const B &b, const C &c)
template
ext::ExtCompletionCallbackWithOutput
< typename
internal::TypeUnwrapper
< Output >::StorageType > 
NewExtCallbackWithOutput (void(T::*method)(int32_t, Output, A, B, C), const A &a, const B &b, const C &c)

Detailed Description

template
class pp::CompletionCallbackFactory< T, ThreadTraits >

CompletionCallbackFactory may be used to create CompletionCallback objects that are bound to member functions.

If a factory is destroyed, then any pending callbacks will be cancelled preventing any bound member functions from being called. The CancelAll() method allows pending callbacks to be cancelled without destroying the factory.

Note: CompletionCallbackFactory isn't thread safe, but it is somewhat thread-friendly when used with a thread-safe traits class as the second template element. However, it only guarantees safety for creating a callback from another thread, the callback itself needs to execute on the same thread as the thread that creates/destroys the factory. With this restriction, it is safe to create the CompletionCallbackFactory on the main thread, create callbacks from any thread and pass them to CallOnMainThread().

Example:

   class MyClass {
    public:
     // If an compiler warns on following using |this| in the initializer
     // list, use PP_ALLOW_THIS_IN_INITIALIZER_LIST macro.
     MyClass() : factory_(this) {
     }

     void OpenFile(const pp::FileRef& file) {
       pp::CompletionCallback cc = factory_.NewCallback(&MyClass::DidOpen);
       int32_t rv = file_io_.Open(file, PP_FileOpenFlag_Read, cc);
       CHECK(rv == PP_OK_COMPLETIONPENDING);
     }

    private:
     void DidOpen(int32_t result) {
       if (result == PP_OK) {
         // The file is open, and we can begin reading.
         // ...
       } else {
         // Failed to open the file with error given by 'result'.
       }
     }

     pp::CompletionCallbackFactory factory_;
   };

Passing additional parameters to your callback

As a convenience, the CompletionCallbackFactory can optionally create a closure with up to three bound parameters that it will pass to your callback function. This can be useful for passing information about the request to your callback function, which is especially useful if your class has multiple asynchronous callbacks pending.

For the above example, of opening a file, let's say you want to keep some description associated with your request, you might implement your OpenFile and DidOpen callback as follows:

   void OpenFile(const pp::FileRef& file) {
     std::string message = "Opening file!";
     pp::CompletionCallback cc = factory_.NewCallback(&MyClass::DidOpen,
                                                      message);
     int32_t rv = file_io_.Open(file, PP_FileOpenFlag_Read, cc);
     CHECK(rv == PP_OK_COMPLETIONPENDING);
   }
   void DidOpen(int32_t result, const std::string& message) {
     // "message" will be "Opening file!".
     ...
   }

Optional versus required callbacks

When you create an "optional" callback, the browser may return the results synchronously if they are available. This can allow for higher performance in some cases if data is available quickly (for example, for network loads where there may be a lot of data coming quickly). In this case, the callback will never be run.

When creating a new callback with the factory, there will be data allocated on the heap that tracks the callback information and any bound arguments. This data is freed when the callback executes. In the case of optional callbacks, since the browser will never issue the callback, the internal tracking data will be leaked.

Therefore, if you use optional callbacks, it's important to manually issue the callback to free up this data. The typical pattern is:

   pp::CompletionCallback callback = callback_factory.NewOptionalCallback(
       &MyClass::OnDataReady);
   int32_t result = interface->GetData(callback);
   if (result != PP_OK_COMPLETIONPENDING)
      callback.Run(result);

Because of this additional complexity, it's generally recommended that you not use optional callbacks except when performance is more important (such as loading large resources from the network). In most other cases, the performance difference will not be worth the additional complexity, and most functions may never actually have the ability to complete synchronously.

Completion callbacks with output

For some API calls, the browser returns data to the caller via an output parameter. These can be difficult to manage since the output parameter must remain valid for as long as the callback is pending. Note also that CancelAll (or destroying the callback factory) does not cancel the callback from the browser's perspective, only the execution of the callback in the plugin code, and the output parameter will still be written to! This means that you can't use class members as output parameters without risking crashes.

To make this case easier, the CompletionCallbackFactory can allocate and manage the output data for you and pass it to your callback function. This makes such calls more natural and less error-prone.

To create such a callback, use NewCallbackWithOutput and specify a callback function that takes the output parameter as its second argument. Let's say you're calling a function GetFile which asynchronously returns a pp::FileRef. GetFile's signature will be int32_t GetFile(const CompletionCallbackWithOutput& callback); and your calling code would look like this:

   void RequestFile() {
     file_interface->GetFile(callback_factory_.NewCallbackWithOutput(
         &MyClass::GotFile));
   }
   void GotFile(int32_t result, const pp::FileRef& file) {
     if (result == PP_OK) {
       ...use file...
     } else {
       ...handle error...
     }
   }

As with regular completion callbacks, you can optionally add up to three bound arguments. These are passed following the output argument.

Your callback may take the output argument as a copy (common for small types like integers, a const reference (common for structures and resources to avoid an extra copy), or as a non-const reference. One optimization you can do if your callback function may take large arrays is to accept your output argument as a non-const reference and to swap() the argument with a vector of your own to store it. This means you don't have to copy the buffer to consume it.

NewExtCallbackWithOutput is similar to NewCallbackWithOutput. It creates ext::ExtCompletionCallbackWithOutput instances which are used by APIs within the pp::ext namespace.


Constructor and Destructor Details

template
pp::CompletionCallbackFactory< T, ThreadTraits >::CompletionCallbackFactory ( T *  object = NULL) [inline, explicit]

This constructor creates a CompletionCallbackFactory bound to an object.

If the constructor is called without an argument, the default value of NULL is used. The user then must call Initialize() to initialize the object.

param[in] object Optional parameter. An object whose member functions are to be bound to CompletionCallbacks created by this CompletionCallbackFactory. The default value of this parameter is NULL.

template
pp::CompletionCallbackFactory< T, ThreadTraits >::~CompletionCallbackFactory ( ) [inline]

Destructor.


Function Details

template
void pp::CompletionCallbackFactory< T, ThreadTraits >::CancelAll ( ) [inline]

CancelAll() cancels all CompletionCallbacks allocated from this factory.

template
T* pp::CompletionCallbackFactory< T, ThreadTraits >::GetObject ( ) [inline]

GetObject() returns the object that was passed at initialization to Intialize().

Returns:
the object passed to the constructor or Intialize().
template
void pp::CompletionCallbackFactory< T, ThreadTraits >::Initialize ( T *  object) [inline]

Initialize() binds the CallbackFactory to a particular object.

Use this when the object is not available at CallbackFactory creation, and the NULL default is passed to the constructor. The object may only be initialized once, either by the constructor, or by a call to Initialize().

This class may not be used on any thread until initialization is complete.

Parameters:
[in]objectThe object whose member functions are to be bound to the CompletionCallback created by this CompletionCallbackFactory.
template
template
CompletionCallback pp::CompletionCallbackFactory< T, ThreadTraits >::NewCallback ( Method  method) [inline]

NewCallback allocates a new, single-use CompletionCallback.

The CompletionCallback must be run in order for the memory allocated by the methods to be freed.

Parameters:
[in]methodThe method to be invoked upon completion of the operation.
Returns:
A CompletionCallback.
template
template
CompletionCallback pp::CompletionCallbackFactory< T, ThreadTraits >::NewCallback ( Method  method,
const A &  a 
) [inline]

NewCallback() allocates a new, single-use CompletionCallback.

The CompletionCallback must be run in order for the memory allocated by the methods to be freed.

Parameters:
[in]methodThe method to be invoked upon completion of the operation. Method should be of type: void (T::*)(int32_t result, const A& a)
[in]aPassed to method when the completion callback runs.
Returns:
A CompletionCallback.
template
template
CompletionCallback pp::CompletionCallbackFactory< T, ThreadTraits >::NewCallback ( Method  method,
const A &  a,
const B &  b,
const C &  c 
) [inline]

NewCallback() allocates a new, single-use CompletionCallback.

The CompletionCallback must be run in order for the memory allocated by the methods to be freed.

Parameters:
methodThe method taking the callback. Method should be of type: void (T::*)(int32_t result, const A& a, const B& b, const C& c)
[in]aPassed to method when the completion callback runs.
[in]bPassed to method when the completion callback runs.
[in]cPassed to method when the completion callback runs.
Returns:
A CompletionCallback.
template
template
CompletionCallback pp::CompletionCallbackFactory< T, ThreadTraits >::NewCallback ( Method  method,
const A &  a,
const B &  b 
) [inline]

NewCallback() allocates a new, single-use CompletionCallback.

The CompletionCallback must be run in order for the memory allocated by the methods to be freed.

Parameters:
methodThe method taking the callback. Method should be of type: void (T::*)(int32_t result, const A& a, const B& b)
[in]aPassed to method when the completion callback runs.
[in]bPassed to method when the completion callback runs.
Returns:
A CompletionCallback.
template
template
CompletionCallbackWithOutput< typename internal::TypeUnwrapper::StorageType> pp::CompletionCallbackFactory< T, ThreadTraits >::NewCallbackWithOutput ( void(T::*)(int32_t, Output, A, B, C)  method,
const A &  a,
const B &  b,
const C &  c 
) [inline]

NewCallbackWithOutput() allocates a new, single-use CompletionCallback where the browser will pass an additional parameter containing the result of the request.

The CompletionCallback must be run in order for the memory allocated by the methods to be freed.

Parameters:
methodThe method to be run.
[in]aPassed to method when the completion callback runs.
[in]bPassed to method when the completion callback runs.
[in]cPassed to method when the completion callback runs.
Returns:
A CompletionCallback.
template
template
CompletionCallbackWithOutput< typename internal::TypeUnwrapper::StorageType> pp::CompletionCallbackFactory< T, ThreadTraits >::NewCallbackWithOutput ( void(T::*)(int32_t, Output, A)  method,
const A &  a 
) [inline]

NewCallbackWithOutput() allocates a new, single-use CompletionCallback where the browser will pass an additional parameter containing the result of the request.

The CompletionCallback must be run in order for the memory allocated by the methods to be freed.

Parameters:
[in]methodThe method to be invoked upon completion of the operation.
[in]aPassed to method when the completion callback runs.
Returns:
A CompletionCallback.
template
template
CompletionCallbackWithOutput< typename internal::TypeUnwrapper::StorageType> pp::CompletionCallbackFactory< T, ThreadTraits >::NewCallbackWithOutput ( void(T::*)(int32_t, Output)  method) [inline]

NewCallbackWithOutput() allocates a new, single-use CompletionCallback where the browser will pass an additional parameter containing the result of the request.

The CompletionCallback must be run in order for the memory allocated by the methods to be freed.

Parameters:
[in]methodThe method to be invoked upon completion of the operation.
Returns:
A CompletionCallback.
template
template
CompletionCallbackWithOutput< typename internal::TypeUnwrapper::StorageType> pp::CompletionCallbackFactory< T, ThreadTraits >::NewCallbackWithOutput ( void(T::*)(int32_t, Output, A, B)  method,
const A &  a,
const B &  b 
) [inline]

NewCallbackWithOutput() allocates a new, single-use CompletionCallback where the browser will pass an additional parameter containing the result of the request.

The CompletionCallback must be run in order for the memory allocated by the methods to be freed.

Parameters:
[in]methodThe method to be invoked upon completion of the operation.
[in]aPassed to method when the completion callback runs.
[in]bPassed to method when the completion callback runs.
Returns:
A CompletionCallback.
template
template
ext::ExtCompletionCallbackWithOutput< typename internal::TypeUnwrapper::StorageType> pp::CompletionCallbackFactory< T, ThreadTraits >::NewExtCallbackWithOutput ( void(T::*)(int32_t, Output, A, B, C)  method,
const A &  a,
const B &  b,
const C &  c 
) [inline]
template
template
ext::ExtCompletionCallbackWithOutput< typename internal::TypeUnwrapper::StorageType> pp::CompletionCallbackFactory< T, ThreadTraits >::NewExtCallbackWithOutput ( void(T::*)(int32_t, Output, A, B)  method,
const A &  a,
const B &  b 
) [inline]
template
template
ext::ExtCompletionCallbackWithOutput< typename internal::TypeUnwrapper::StorageType> pp::CompletionCallbackFactory< T, ThreadTraits >::NewExtCallbackWithOutput ( void(T::*)(int32_t, Output, A)  method,
const A &  a 
) [inline]
template
template
ext::ExtCompletionCallbackWithOutput< typename internal::TypeUnwrapper::StorageType> pp::CompletionCallbackFactory< T, ThreadTraits >::NewExtCallbackWithOutput ( void(T::*)(int32_t, Output)  method) [inline]
template
template
CompletionCallback pp::CompletionCallbackFactory< T, ThreadTraits >::NewOptionalCallback ( Method  method,
const A &  a,
const B &  b,
const C &  c 
) [inline]

NewOptionalCallback() allocates a new, single-use CompletionCallback that might not run if the method taking it can complete synchronously.

Thus, if after passing the CompletionCallback to a Pepper method, the method does not return PP_OK_COMPLETIONPENDING, then you should manually call the CompletionCallback's Run method, or memory will be leaked.

Parameters:
[in]methodThe method taking the callback. Method should be of type: void (T::*)(int32_t result, const A& a, const B& b, const C& c)
[in]aPassed to method when the completion callback runs.
[in]bPassed to method when the completion callback runs.
[in]cPassed to method when the completion callback runs.
Returns:
A CompletionCallback.
template
template
CompletionCallback pp::CompletionCallbackFactory< T, ThreadTraits >::NewOptionalCallback ( Method  method,
const A &  a 
) [inline]

NewOptionalCallback() allocates a new, single-use CompletionCallback that might not run if the method taking it can complete synchronously.

Thus, if after passing the CompletionCallback to a Pepper method, the method does not return PP_OK_COMPLETIONPENDING, then you should manually call the CompletionCallback's Run method, or memory will be leaked.

Parameters:
[in]methodThe method to be invoked upon completion of the operation. Method should be of type: void (T::*)(int32_t result, const A& a)
[in]aPassed to method when the completion callback runs.
Returns:
A CompletionCallback.
template
template
CompletionCallback pp::CompletionCallbackFactory< T, ThreadTraits >::NewOptionalCallback ( Method  method) [inline]

NewOptionalCallback() allocates a new, single-use CompletionCallback that might not run if the method taking it can complete synchronously.

Thus, if after passing the CompletionCallback to a Pepper method, the method does not return PP_OK_COMPLETIONPENDING, then you should manually call the CompletionCallback's Run method, or memory will be leaked.

Parameters:
[in]methodThe method to be invoked upon completion of the operation.
Returns:
A CompletionCallback.
template
template
CompletionCallback pp::CompletionCallbackFactory< T, ThreadTraits >::NewOptionalCallback ( Method  method,
const A &  a,
const B &  b 
) [inline]

NewOptionalCallback() allocates a new, single-use CompletionCallback that might not run if the method taking it can complete synchronously.

Thus, if after passing the CompletionCallback to a Pepper method, the method does not return PP_OK_COMPLETIONPENDING, then you should manually call the CompletionCallback's Run method, or memory will be leaked.

Parameters:
[in]methodThe method taking the callback. Method should be of type: void (T::*)(int32_t result, const A& a, const B& b)
[in]aPassed to method when the completion callback runs.
[in]bPassed to method when the completion callback runs.
Returns:
A CompletionCallback.

The documentation for this class was generated from the following file:

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.