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

template<typename T , typename ThreadTraits = ThreadSafeThreadTraits>

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<typename T , typename ThreadTraits = ThreadSafeThreadTraits>

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

Destructor.

Member Function Documentation

template<typename T , typename ThreadTraits = ThreadSafeThreadTraits>

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

CancelAll() cancels all CompletionCallbacks allocated from this factory.

template<typename T , typename ThreadTraits = ThreadSafeThreadTraits>

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<typename T , typename ThreadTraits = ThreadSafeThreadTraits>

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 this CompletionCallbackFactory.

template<typename T , typename ThreadTraits = ThreadSafeThreadTraits>

template<typename Method >

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.

template<typename T , typename ThreadTraits = ThreadSafeThreadTraits>

template<typename Method , typename A >

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.

template<typename T , typename ThreadTraits = ThreadSafeThreadTraits>

template<typename Method , typename A , typename B >

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.

template<typename T , typename ThreadTraits = ThreadSafeThreadTraits>

template<typename Method , typename A , typename B , typename C >

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.

template<typename T , typename ThreadTraits = ThreadSafeThreadTraits>

template<typename Output >

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.

template<typename T , typename ThreadTraits = ThreadSafeThreadTraits>

template<typename Output , typename A >

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.

template<typename T , typename ThreadTraits = ThreadSafeThreadTraits>

template<typename Output , typename A , typename B >

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.

template<typename T , typename ThreadTraits = ThreadSafeThreadTraits>

template<typename Output , typename A , typename B , typename C >

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.

template<typename T , typename ThreadTraits = ThreadSafeThreadTraits>

template<typename Method >

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.

template<typename T , typename ThreadTraits = ThreadSafeThreadTraits>

template<typename Method , typename A >

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.

template<typename T , typename ThreadTraits = ThreadSafeThreadTraits>

template<typename Method , typename A , typename B >

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.

template<typename T , typename ThreadTraits = ThreadSafeThreadTraits>

template<typename Method , typename A , typename B , typename C >

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:

completion_callback_factory.h

Classes

Public Member Functions

Detailed Description

template<typename T, typename ThreadTraits = ThreadSafeThreadTraits> class pp::CompletionCallbackFactory< T, ThreadTraits >

Constructor & Destructor Documentation

Member Function Documentation

template<typename T, typename ThreadTraits = ThreadSafeThreadTraits>
class pp::CompletionCallbackFactory< T, ThreadTraits >