Classes
class | BackPointer |
class | CallbackData |
class | Dispatcher0 |
class | Dispatcher1 |
class | Dispatcher2 |
class | Dispatcher3 |
class | DispatcherWithOutput0 |
class | DispatcherWithOutput1 |
class | DispatcherWithOutput2 |
class | DispatcherWithOutput3 |
Public Member Functions
CompletionCallbackFactory (T *object=NULL) | |
~CompletionCallbackFactory () | |
void | CancelAll () |
void | Initialize (T *object) |
T * | GetObject () |
template<typename Method > | |
CompletionCallback | NewCallback (Method method) |
template<typename Method > | |
CompletionCallback | NewOptionalCallback (Method method) |
template<typename Output > | |
CompletionCallbackWithOutput < typename internal::TypeUnwrapper < Output >::StorageType > | NewCallbackWithOutput (void(T::*method)(int32_t, Output)) |
template<typename Method , typename A > | |
CompletionCallback | NewCallback (Method method, const A &a) |
template<typename Method , typename A > | |
CompletionCallback | NewOptionalCallback (Method method, const A &a) |
template<typename Output , typename A > | |
CompletionCallbackWithOutput < typename internal::TypeUnwrapper < Output >::StorageType > | NewCallbackWithOutput (void(T::*method)(int32_t, Output, A), const A &a) |
template<typename Method , typename A , typename B > | |
CompletionCallback | NewCallback (Method method, const A &a, const B &b) |
template<typename Method , typename A , typename B > | |
CompletionCallback | NewOptionalCallback (Method method, const A &a, const B &b) |
template<typename Output , typename A , typename B > | |
CompletionCallbackWithOutput < typename internal::TypeUnwrapper < Output >::StorageType > | NewCallbackWithOutput (void(T::*method)(int32_t, Output, A, B), const A &a, const B &b) |
template<typename Method , typename A , typename B , typename C > | |
CompletionCallback | NewCallback (Method method, const A &a, const B &b, const C &c) |
template<typename Method , typename A , typename B , typename C > | |
CompletionCallback | NewOptionalCallback (Method method, const A &a, const B &b, const C &c) |
template<typename Output , typename A , typename B , typename C > | |
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) |
Detailed Description
template<typename T, typename ThreadTraits = ThreadSafeThreadTraits>
class pp::CompletionCallbackFactory< T, ThreadTraits >
CompletionCallbackFactory<T> 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<T>
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<MyClass> 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<pp::FileRef>& 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.
Constructor & Destructor Documentation
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
.
pp::CompletionCallbackFactory< T, ThreadTraits >::~CompletionCallbackFactory | ( | ) | [inline] |
Destructor.
Member Function Documentation
void pp::CompletionCallbackFactory< T, ThreadTraits >::CancelAll | ( | ) | [inline] |
CancelAll() cancels all CompletionCallbacks
allocated from this factory.
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().
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] object The object whose member functions are to be bound to the CompletionCallback
created by thisCompletionCallbackFactory
.
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] method The method to be invoked upon completion of the operation.
- Returns:
- A
CompletionCallback
.
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] method The method to be invoked upon completion of the operation. Method should be of type: void (T::*)(int32_t result, const A& a)
[in] a Passed to method
when the completion callback runs.
- Returns:
- A
CompletionCallback
.
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:
method The method taking the callback. Method should be of type: void (T::*)(int32_t result, const A& a, const B& b)
[in] a Passed to method
when the completion callback runs.[in] b Passed to method
when the completion callback runs.
- Returns:
- A
CompletionCallback
.
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:
method The method taking the callback. Method should be of type: void (T::*)(int32_t result, const A& a, const B& b, const C& c)
[in] a Passed to method
when the completion callback runs.[in] b Passed to method
when the completion callback runs.[in] c Passed to method
when the completion callback runs.
- Returns:
- A
CompletionCallback
.
CompletionCallbackWithOutput< typename internal::TypeUnwrapper<Output>::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] method The method to be invoked upon completion of the operation.
- Returns:
- A
CompletionCallback
.
CompletionCallbackWithOutput< typename internal::TypeUnwrapper<Output>::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] method The method to be invoked upon completion of the operation. [in] a Passed to method
when the completion callback runs.
- Returns:
- A
CompletionCallback
.
CompletionCallbackWithOutput< typename internal::TypeUnwrapper<Output>::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] method The method to be invoked upon completion of the operation. [in] a Passed to method
when the completion callback runs.[in] b Passed to method
when the completion callback runs.
- Returns:
- A
CompletionCallback
.
CompletionCallbackWithOutput< typename internal::TypeUnwrapper<Output>::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:
method The method to be run. [in] a Passed to method
when the completion callback runs.[in] b Passed to method
when the completion callback runs.[in] c Passed to method
when the completion callback runs.
- Returns:
- A
CompletionCallback
.
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] method The method to be invoked upon completion of the operation.
- Returns:
- A
CompletionCallback
.
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] method The method to be invoked upon completion of the operation. Method should be of type: void (T::*)(int32_t result, const A& a)
[in] a Passed to method
when the completion callback runs.
- Returns:
- A
CompletionCallback
.
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] method The method taking the callback. Method should be of type: void (T::*)(int32_t result, const A& a, const B& b)
[in] a Passed to method
when the completion callback runs.[in] b Passed to method
when the completion callback runs.
- Returns:
- A
CompletionCallback
.
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] method The method taking the callback. Method should be of type: void (T::*)(int32_t result, const A& a, const B& b, const C& c)
[in] a Passed to method
when the completion callback runs.[in] b Passed to method
when the completion callback runs.[in] c Passed to method
when the completion callback runs.
- Returns:
- A
CompletionCallback
.
The documentation for this class was generated from the following file: