completion_callback_factory.h

// Copyright (c) 2012 The Chromium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

#ifndef PPAPI_UTILITY_COMPLETION_CALLBACK_FACTORY_H_
#define PPAPI_UTILITY_COMPLETION_CALLBACK_FACTORY_H_

#include "ppapi/cpp/completion_callback.h"
#include "ppapi/utility/completion_callback_factory_thread_traits.h"

/// @file
/// This file defines the API to create CompletionCallback objects that are
/// bound to member functions.
namespace pp {

// TypeUnwrapper --------------------------------------------------------------

namespace internal {

// The TypeUnwrapper converts references and const references to the
// underlying type used for storage and passing as an argument. It is for
// internal use only.
template <typename T> struct TypeUnwrapper {
  typedef T StorageType;
};
template <typename T> struct TypeUnwrapper<T&> {
  typedef T StorageType;
};
template <typename T> struct TypeUnwrapper<const T&> {
  typedef T StorageType;
};

}  // namespace internal

// ----------------------------------------------------------------------------

/// 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.
///
/// <strong>Note: </strong><code>CompletionCallbackFactory<T></code> 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 <code>CompletionCallbackFactory</code> on the main thread, create
/// callbacks from any thread and pass them to CallOnMainThread().
///
/// <strong>Example: </strong>
///
/// @code
///   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_;
///   };
/// @endcode
///
/// <strong>Passing additional parameters to your callback</strong>
///
/// As a convenience, the <code>CompletionCallbackFactory</code> 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:
///
/// @code
///   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!".
///     ...
///   }
/// @endcode
///
/// <strong>Optional versus required callbacks</strong>
///
/// 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:
///
/// @code
///   pp::CompletionCallback callback = callback_factory.NewOptionalCallback(
///       &MyClass::OnDataReady);
///   int32_t result = interface->GetData(callback);
///   if (result != PP_OK_COMPLETIONPENDING)
///      callback.Run(result);
/// @endcode
///
/// 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.
///
/// <strong>Completion callbacks with output</strong>
///
/// 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 <i>not</i> 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 <code>int32_t GetFile(const
/// CompletionCallbackWithOutput<pp::FileRef>& callback);</code> and your
/// calling code would look like this:
///
/// @code
///   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...
///     }
///   }
/// @endcode
///
/// 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.
template <typename T, typename ThreadTraits = ThreadSafeThreadTraits>
class CompletionCallbackFactory {
 public:

  /// This constructor creates a <code>CompletionCallbackFactory</code>
  /// bound to an object. If the constructor is called without an argument,
  /// the default value of <code>NULL</code> 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
  /// <code>CompletionCallbackFactory</code>. The default value of this
  /// parameter is <code>NULL</code>.
  explicit CompletionCallbackFactory(T* object = NULL)
      : object_(object) {
    // Assume that we don't need to lock since construction should be complete
    // before the pointer is used on another thread.
    InitBackPointer();
  }

  /// Destructor.
  ~CompletionCallbackFactory() {
    // Assume that we don't need to lock since this object should not be used
    // from multiple threads during destruction.
    ResetBackPointer();
  }

  /// CancelAll() cancels all <code>CompletionCallbacks</code> allocated from
  /// this factory.
  void CancelAll() {
    typename ThreadTraits::AutoLock lock(lock_);

    ResetBackPointer();
    InitBackPointer();
  }

  /// Initialize() binds the <code>CallbackFactory</code> to a particular
  /// object. Use this when the object is not available at
  /// <code>CallbackFactory</code> creation, and the <code>NULL</code> 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.
  ///
  /// @param[in] object The object whose member functions are to be bound to
  /// the <code>CompletionCallback</code> created by this
  /// <code>CompletionCallbackFactory</code>.
  void Initialize(T* object) {
    PP_DCHECK(object);
    PP_DCHECK(!object_);  // May only initialize once!
    object_ = object;
  }

  /// GetObject() returns the object that was passed at initialization to
  /// Intialize().
  ///
  /// @return the object passed to the constructor or Intialize().
  T* GetObject() {
    return object_;
  }

  /// NewCallback allocates a new, single-use <code>CompletionCallback</code>.
  /// The <code>CompletionCallback</code> must be run in order for the memory
  /// allocated by the methods to be freed.
  ///
  /// @param[in] method The method to be invoked upon completion of the
  /// operation.
  ///
  /// @return A <code>CompletionCallback</code>.
  template <typename Method>
  CompletionCallback NewCallback(Method method) {
    return NewCallbackHelper(new Dispatcher0<Method>(method));
  }

  /// NewOptionalCallback() allocates a new, single-use
  /// <code>CompletionCallback</code> 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.
  ///
  /// @param[in] method The method to be invoked upon completion of the
  /// operation.
  ///
  /// @return A <code>CompletionCallback</code>.
  template <typename Method>
  CompletionCallback NewOptionalCallback(Method method) {
    CompletionCallback cc = NewCallback(method);
    cc.set_flags(cc.flags() | PP_COMPLETIONCALLBACK_FLAG_OPTIONAL);
    return cc;
  }

  /// NewCallbackWithOutput() allocates a new, single-use
  /// <code>CompletionCallback</code> where the browser will pass an additional
  /// parameter containing the result of the request. The
  /// <code>CompletionCallback</code> must be run in order for the memory
  /// allocated by the methods to be freed.
  ///
  /// @param[in] method The method to be invoked upon completion of the
  /// operation.
  ///
  /// @return A <code>CompletionCallback</code>.
  template <typename Output>
  CompletionCallbackWithOutput<
      typename internal::TypeUnwrapper<Output>::StorageType>
  NewCallbackWithOutput(void (T::*method)(int32_t, Output)) {
    typedef typename internal::TypeUnwrapper<Output>::StorageType
        OutputStorageType;
    typedef CompletionCallbackWithOutput<OutputStorageType> CallbackType;
    typedef DispatcherWithOutput0<
        typename CallbackType::TraitsType,
        OutputStorageType,
        void (T::*)(int32_t, Output)> DispatcherType;
    return NewCallbackWithOutputHelper<CallbackType>(
        new DispatcherType(method));
  }

  /// Similar to NewCallbackWithOutput(), but returns an
  /// <code>ext::ExtCompletionCallbackWithOutput</code>.
  template <typename Output>
  ext::ExtCompletionCallbackWithOutput<
      typename internal::TypeUnwrapper<Output>::StorageType>
  NewExtCallbackWithOutput(void (T::*method)(int32_t, Output)) {
    typedef typename internal::TypeUnwrapper<Output>::StorageType
        OutputStorageType;
    typedef ext::ExtCompletionCallbackWithOutput<OutputStorageType>
        CallbackType;
    typedef DispatcherWithOutput0<
        typename CallbackType::TraitsType,
        OutputStorageType,
        void (T::*)(int32_t, Output)> DispatcherType;
    return NewCallbackWithOutputHelper<CallbackType>(
        new DispatcherType(method));
  }

  /// NewCallback() allocates a new, single-use <code>CompletionCallback</code>.
  /// The <code>CompletionCallback</code> must be run in order for the memory
  /// allocated by the methods to be freed.
  ///
  /// @param[in] method The method to be invoked upon completion of the
  /// operation. Method should be of type:
  /// <code>void (T::*)(int32_t result, const A& a)</code>
  ///
  /// @param[in] a Passed to <code>method</code> when the completion callback
  /// runs.
  ///
  /// @return A <code>CompletionCallback</code>.
  template <typename Method, typename A>
  CompletionCallback NewCallback(Method method, const A& a) {
    return NewCallbackHelper(new Dispatcher1<Method, A>(method, a));
  }

  /// NewOptionalCallback() allocates a new, single-use
  /// <code>CompletionCallback</code> 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.
  ///
  /// @param[in] method The method to be invoked upon completion of the
  /// operation. Method should be of type:
  /// <code>void (T::*)(int32_t result, const A& a)</code>
  ///
  /// @param[in] a Passed to <code>method</code> when the completion callback
  /// runs.
  ///
  /// @return A <code>CompletionCallback</code>.
  template <typename Method, typename A>
  CompletionCallback NewOptionalCallback(Method method, const A& a) {
    CompletionCallback cc = NewCallback(method, a);
    cc.set_flags(cc.flags() | PP_COMPLETIONCALLBACK_FLAG_OPTIONAL);
    return cc;
  }

  /// NewCallbackWithOutput() allocates a new, single-use
  /// <code>CompletionCallback</code> where the browser will pass an additional
  /// parameter containing the result of the request. The
  /// <code>CompletionCallback</code> must be run in order for the memory
  /// allocated by the methods to be freed.
  ///
  /// @param[in] method The method to be invoked upon completion of the
  /// operation.
  ///
  /// @param[in] a Passed to <code>method</code> when the completion callback
  /// runs.
  ///
  /// @return A <code>CompletionCallback</code>.
  template <typename Output, typename A>
  CompletionCallbackWithOutput<
      typename internal::TypeUnwrapper<Output>::StorageType>
  NewCallbackWithOutput(void (T::*method)(int32_t, Output, A),
                        const A& a) {
    typedef typename internal::TypeUnwrapper<Output>::StorageType
        OutputStorageType;
    typedef CompletionCallbackWithOutput<OutputStorageType> CallbackType;
    typedef DispatcherWithOutput1<
        typename CallbackType::TraitsType,
        OutputStorageType,
        void (T::*)(int32_t, Output, A),
        typename internal::TypeUnwrapper<A>::StorageType> DispatcherType;
    return NewCallbackWithOutputHelper<CallbackType>(
        new DispatcherType(method, a));
  }

  /// Similar to NewCallbackWithOutput(), but returns an
  /// <code>ext::ExtCompletionCallbackWithOutput</code>.
  template <typename Output, typename A>
  ext::ExtCompletionCallbackWithOutput<
      typename internal::TypeUnwrapper<Output>::StorageType>
  NewExtCallbackWithOutput(void (T::*method)(int32_t, Output, A),
                           const A& a) {
    typedef typename internal::TypeUnwrapper<Output>::StorageType
        OutputStorageType;
    typedef ext::ExtCompletionCallbackWithOutput<OutputStorageType>
        CallbackType;
    typedef DispatcherWithOutput1<
        typename CallbackType::TraitsType,
        OutputStorageType,
        void (T::*)(int32_t, Output, A),
        typename internal::TypeUnwrapper<A>::StorageType> DispatcherType;
    return NewCallbackWithOutputHelper<CallbackType>(
        new DispatcherType(method, a));
  }

  /// NewCallback() allocates a new, single-use
  /// <code>CompletionCallback</code>.
  /// The <code>CompletionCallback</code> must be run in order for the memory
  /// allocated by the methods to be freed.
  ///
  /// @param method The method taking the callback. Method should be of type:
  /// <code>void (T::*)(int32_t result, const A& a, const B& b)</code>
  ///
  /// @param[in] a Passed to <code>method</code> when the completion callback
  /// runs.
  ///
  /// @param[in] b Passed to <code>method</code> when the completion callback
  /// runs.
  ///
  /// @return A <code>CompletionCallback</code>.
  template <typename Method, typename A, typename B>
  CompletionCallback NewCallback(Method method, const A& a, const B& b) {
    return NewCallbackHelper(new Dispatcher2<Method, A, B>(method, a, b));
  }

  /// NewOptionalCallback() allocates a new, single-use
  /// <code>CompletionCallback</code> 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.
  ///
  /// @param[in] method The method taking the callback. Method should be of
  /// type:
  /// <code>void (T::*)(int32_t result, const A& a, const B& b)</code>
  ///
  /// @param[in] a Passed to <code>method</code> when the completion callback
  /// runs.
  ///
  /// @param[in] b Passed to <code>method</code> when the completion callback
  /// runs.
  ///
  /// @return A <code>CompletionCallback</code>.
  template <typename Method, typename A, typename B>
  CompletionCallback NewOptionalCallback(Method method, const A& a,
                                         const B& b) {
    CompletionCallback cc = NewCallback(method, a, b);
    cc.set_flags(cc.flags() | PP_COMPLETIONCALLBACK_FLAG_OPTIONAL);
    return cc;
  }

  /// NewCallbackWithOutput() allocates a new, single-use
  /// <code>CompletionCallback</code> where the browser will pass an additional
  /// parameter containing the result of the request. The
  /// <code>CompletionCallback</code> must be run in order for the memory
  /// allocated by the methods to be freed.
  ///
  /// @param[in] method The method to be invoked upon completion of the
  /// operation.
  ///
  /// @param[in] a Passed to <code>method</code> when the completion callback
  /// runs.
  ///
  /// @param[in] b Passed to <code>method</code> when the completion callback
  /// runs.
  ///
  /// @return A <code>CompletionCallback</code>.
  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) {
    typedef typename internal::TypeUnwrapper<Output>::StorageType
        OutputStorageType;
    typedef CompletionCallbackWithOutput<OutputStorageType> CallbackType;
    typedef DispatcherWithOutput2<
        typename CallbackType::TraitsType,
        OutputStorageType,
        void (T::*)(int32_t, Output, A, B),
        typename internal::TypeUnwrapper<A>::StorageType,
        typename internal::TypeUnwrapper<B>::StorageType> DispatcherType;
    return NewCallbackWithOutputHelper<CallbackType>(
        new DispatcherType(method, a, b));
  }

  /// Similar to NewCallbackWithOutput(), but returns an
  /// <code>ext::ExtCompletionCallbackWithOutput</code>.
  template <typename Output, typename A, typename B>
  ext::ExtCompletionCallbackWithOutput<
      typename internal::TypeUnwrapper<Output>::StorageType>
  NewExtCallbackWithOutput(void (T::*method)(int32_t, Output, A, B),
                           const A& a,
                           const B& b) {
    typedef typename internal::TypeUnwrapper<Output>::StorageType
        OutputStorageType;
    typedef ext::ExtCompletionCallbackWithOutput<OutputStorageType>
        CallbackType;
    typedef DispatcherWithOutput2<
        typename CallbackType::TraitsType,
        OutputStorageType,
        void (T::*)(int32_t, Output, A, B),
        typename internal::TypeUnwrapper<A>::StorageType,
        typename internal::TypeUnwrapper<B>::StorageType> DispatcherType;
    return NewCallbackWithOutputHelper<CallbackType>(
        new DispatcherType(method, a, b));
  }

  /// NewCallback() allocates a new, single-use
  /// <code>CompletionCallback</code>.
  /// The <code>CompletionCallback</code> must be run in order for the memory
  /// allocated by the methods to be freed.
  ///
  /// @param method The method taking the callback. Method should be of type:
  /// <code>
  /// void (T::*)(int32_t result, const A& a, const B& b, const C& c)
  /// </code>
  ///
  /// @param[in] a Passed to <code>method</code> when the completion callback
  /// runs.
  ///
  /// @param[in] b Passed to <code>method</code> when the completion callback
  /// runs.
  ///
  /// @param[in] c Passed to <code>method</code> when the completion callback
  /// runs.
  ///
  /// @return A <code>CompletionCallback</code>.
  template <typename Method, typename A, typename B, typename C>
  CompletionCallback NewCallback(Method method, const A& a, const B& b,
                                 const C& c) {
    return NewCallbackHelper(new Dispatcher3<Method, A, B, C>(method, a, b, c));
  }

  /// NewOptionalCallback() allocates a new, single-use
  /// <code>CompletionCallback</code> 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.
  ///
  /// @param[in] method The method taking the callback. Method should be of
  /// type:
  /// <code>
  /// void (T::*)(int32_t result, const A& a, const B& b, const C& c)
  /// </code>
  ///
  /// @param[in] a Passed to <code>method</code> when the completion callback
  /// runs.
  ///
  /// @param[in] b Passed to <code>method</code> when the completion callback
  /// runs.
  ///
  /// @param[in] c Passed to <code>method</code> when the completion callback
  /// runs.
  ///
  /// @return A <code>CompletionCallback</code>.
  template <typename Method, typename A, typename B, typename C>
  CompletionCallback NewOptionalCallback(Method method, const A& a,
                                         const B& b, const C& c) {
    CompletionCallback cc = NewCallback(method, a, b, c);
    cc.set_flags(cc.flags() | PP_COMPLETIONCALLBACK_FLAG_OPTIONAL);
    return cc;
  }

  /// NewCallbackWithOutput() allocates a new, single-use
  /// <code>CompletionCallback</code> where the browser will pass an additional
  /// parameter containing the result of the request. The
  /// <code>CompletionCallback</code> must be run in order for the memory
  /// allocated by the methods to be freed.
  ///
  /// @param method The method to be run.
  ///
  /// @param[in] a Passed to <code>method</code> when the completion callback
  /// runs.
  ///
  /// @param[in] b Passed to <code>method</code> when the completion callback
  /// runs.
  ///
  /// @param[in] c Passed to <code>method</code> when the completion callback
  /// runs.
  ///
  /// @return A <code>CompletionCallback</code>.
  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) {
    typedef typename internal::TypeUnwrapper<Output>::StorageType
        OutputStorageType;
    typedef CompletionCallbackWithOutput<OutputStorageType> CallbackType;
    typedef DispatcherWithOutput3<
        typename CallbackType::TraitsType,
        OutputStorageType,
        void (T::*)(int32_t, Output, A, B, C),
        typename internal::TypeUnwrapper<A>::StorageType,
        typename internal::TypeUnwrapper<B>::StorageType,
        typename internal::TypeUnwrapper<C>::StorageType> DispatcherType;
    return NewCallbackWithOutputHelper<CallbackType>(
        new DispatcherType(method, a, b, c));
  }

  /// Similar to NewCallbackWithOutput(), but returns an
  /// <code>ext::ExtCompletionCallbackWithOutput</code>.
  template <typename Output, typename A, typename B, typename C>
  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) {
    typedef typename internal::TypeUnwrapper<Output>::StorageType
        OutputStorageType;
    typedef ext::ExtCompletionCallbackWithOutput<OutputStorageType>
        CallbackType;
    typedef DispatcherWithOutput3<
        typename CallbackType::TraitsType,
        OutputStorageType,
        void (T::*)(int32_t, Output, A, B, C),
        typename internal::TypeUnwrapper<A>::StorageType,
        typename internal::TypeUnwrapper<B>::StorageType,
        typename internal::TypeUnwrapper<C>::StorageType> DispatcherType;
    return NewCallbackWithOutputHelper<CallbackType>(
        new DispatcherType(method, a, b, c));
  }

 private:
  class BackPointer {
   public:
    typedef CompletionCallbackFactory<T, ThreadTraits> FactoryType;

    explicit BackPointer(FactoryType* factory)
        : factory_(factory) {
    }

    void AddRef() {
      ref_.AddRef();
    }

    void Release() {
      if (ref_.Release() == 0)
        delete this;
    }

    void DropFactory() {
      factory_ = NULL;
    }

    T* GetObject() {
      return factory_ ? factory_->GetObject() : NULL;
    }

   private:
    typename ThreadTraits::RefCount ref_;
    FactoryType* factory_;
  };

  template <typename Dispatcher>
  class CallbackData {
   public:
    // Takes ownership of the given dispatcher pointer.
    CallbackData(BackPointer* back_pointer, Dispatcher* dispatcher)
        : back_pointer_(back_pointer),
          dispatcher_(dispatcher) {
      back_pointer_->AddRef();
    }

    ~CallbackData() {
      back_pointer_->Release();
      delete dispatcher_;
    }

    Dispatcher* dispatcher() { return dispatcher_; }

    static void Thunk(void* user_data, int32_t result) {
      Self* self = static_cast<Self*>(user_data);
      T* object = self->back_pointer_->GetObject();

      // Please note that |object| may be NULL at this point. But we still need
      // to call into Dispatcher::operator() in that case, so that it can do
      // necessary cleanup.
      (*self->dispatcher_)(object, result);

      delete self;
    }

   private:
    typedef CallbackData<Dispatcher> Self;
    BackPointer* back_pointer_;  // We own a ref to this refcounted object.
    Dispatcher* dispatcher_;  // We own this pointer.

    // Disallow copying & assignment.
    CallbackData(const CallbackData<Dispatcher>&);
    CallbackData<Dispatcher>& operator=(const CallbackData<Dispatcher>&);
  };

  template <typename Method>
  class Dispatcher0 {
   public:
    Dispatcher0() : method_(NULL) {}
    explicit Dispatcher0(Method method) : method_(method) {
    }
    void operator()(T* object, int32_t result) {
      if (object)
        (object->*method_)(result);
    }
   private:
    Method method_;
  };

  template <typename Traits, typename Output, typename Method>
  class DispatcherWithOutput0 {
   public:
    typedef Output OutputType;

    DispatcherWithOutput0()
        : method_(NULL),
          output_() {
      Traits::Initialize(&output_);
    }
    DispatcherWithOutput0(Method method)
        : method_(method),
          output_() {
      Traits::Initialize(&output_);
    }
    void operator()(T* object, int32_t result) {
      // We must call Traits::StorageToPluginArg() even if we don't need to call
      // the callback anymore, otherwise we may leak resource or var references.
      if (object)
        (object->*method_)(result, Traits::StorageToPluginArg(output_));
      else
        Traits::StorageToPluginArg(output_);
    }
    typename Traits::StorageType* output() {
      return &output_;
    }
   private:
    Method method_;

    typename Traits::StorageType output_;
  };

  template <typename Method, typename A>
  class Dispatcher1 {
   public:
    Dispatcher1()
        : method_(NULL),
          a_() {
    }
    Dispatcher1(Method method, const A& a)
        : method_(method),
          a_(a) {
    }
    void operator()(T* object, int32_t result) {
      if (object)
        (object->*method_)(result, a_);
    }
   private:
    Method method_;
    A a_;
  };

  template <typename Traits, typename Output, typename Method, typename A>
  class DispatcherWithOutput1 {
   public:
    typedef Output OutputType;

    DispatcherWithOutput1()
        : method_(NULL),
          a_(),
          output_() {
      Traits::Initialize(&output_);
    }
    DispatcherWithOutput1(Method method, const A& a)
        : method_(method),
          a_(a),
          output_() {
      Traits::Initialize(&output_);
    }
    void operator()(T* object, int32_t result) {
      // We must call Traits::StorageToPluginArg() even if we don't need to call
      // the callback anymore, otherwise we may leak resource or var references.
      if (object)
        (object->*method_)(result, Traits::StorageToPluginArg(output_), a_);
      else
        Traits::StorageToPluginArg(output_);
    }
    typename Traits::StorageType* output() {
      return &output_;
    }
   private:
    Method method_;
    A a_;

    typename Traits::StorageType output_;
  };

  template <typename Method, typename A, typename B>
  class Dispatcher2 {
   public:
    Dispatcher2()
        : method_(NULL),
          a_(),
          b_() {
    }
    Dispatcher2(Method method, const A& a, const B& b)
        : method_(method),
          a_(a),
          b_(b) {
    }
    void operator()(T* object, int32_t result) {
      if (object)
        (object->*method_)(result, a_, b_);
    }
   private:
    Method method_;
    A a_;
    B b_;
  };

  template <typename Traits,
            typename Output,
            typename Method,
            typename A,
            typename B>
  class DispatcherWithOutput2 {
   public:
    typedef Output OutputType;

    DispatcherWithOutput2()
        : method_(NULL),
          a_(),
          b_(),
          output_() {
      Traits::Initialize(&output_);
    }
    DispatcherWithOutput2(Method method, const A& a, const B& b)
        : method_(method),
          a_(a),
          b_(b),
          output_() {
      Traits::Initialize(&output_);
    }
    void operator()(T* object, int32_t result) {
      // We must call Traits::StorageToPluginArg() even if we don't need to call
      // the callback anymore, otherwise we may leak resource or var references.
      if (object)
        (object->*method_)(result, Traits::StorageToPluginArg(output_), a_, b_);
      else
        Traits::StorageToPluginArg(output_);
    }
    typename Traits::StorageType* output() {
      return &output_;
    }
   private:
    Method method_;
    A a_;
    B b_;

    typename Traits::StorageType output_;
  };

  template <typename Method, typename A, typename B, typename C>
  class Dispatcher3 {
   public:
    Dispatcher3()
        : method_(NULL),
          a_(),
          b_(),
          c_() {
    }
    Dispatcher3(Method method, const A& a, const B& b, const C& c)
        : method_(method),
          a_(a),
          b_(b),
          c_(c) {
    }
    void operator()(T* object, int32_t result) {
      if (object)
        (object->*method_)(result, a_, b_, c_);
    }
   private:
    Method method_;
    A a_;
    B b_;
    C c_;
  };

  template <typename Traits,
            typename Output,
            typename Method,
            typename A,
            typename B,
            typename C>
  class DispatcherWithOutput3 {
   public:
    typedef Output OutputType;

    DispatcherWithOutput3()
        : method_(NULL),
          a_(),
          b_(),
          c_(),
          output_() {
      Traits::Initialize(&output_);
    }
    DispatcherWithOutput3(Method method, const A& a, const B& b, const C& c)
        : method_(method),
          a_(a),
          b_(b),
          c_(c),
          output_() {
      Traits::Initialize(&output_);
    }
    void operator()(T* object, int32_t result) {
      // We must call Traits::StorageToPluginArg() even if we don't need to call
      // the callback anymore, otherwise we may leak resource or var references.
      if (object) {
        (object->*method_)(result, Traits::StorageToPluginArg(output_),
                           a_, b_, c_);
      } else {
        Traits::StorageToPluginArg(output_);
      }
    }
    typename Traits::StorageType* output() {
      return &output_;
    }
   private:
    Method method_;
    A a_;
    B b_;
    C c_;

    typename Traits::StorageType output_;
  };

  // Creates the back pointer object and takes a reference to it. This assumes
  // either that the lock is held or that it is not needed.
  void InitBackPointer() {
    back_pointer_ = new BackPointer(this);
    back_pointer_->AddRef();
  }

  // Releases our reference to the back pointer object and clears the pointer.
  // This assumes either that the lock is held or that it is not needed.
  void ResetBackPointer() {
    back_pointer_->DropFactory();
    back_pointer_->Release();
    back_pointer_ = NULL;
  }

  // Takes ownership of the dispatcher pointer, which should be heap allocated.
  template <typename Dispatcher>
  CompletionCallback NewCallbackHelper(Dispatcher* dispatcher) {
    typename ThreadTraits::AutoLock lock(lock_);

    PP_DCHECK(object_);  // Expects a non-null object!
    return CompletionCallback(
        &CallbackData<Dispatcher>::Thunk,
        new CallbackData<Dispatcher>(back_pointer_, dispatcher));
  }

  // Takes ownership of the dispatcher pointer, which should be heap allocated.
  template <typename Callback, typename Dispatcher>
  Callback NewCallbackWithOutputHelper(Dispatcher* dispatcher) {
    typename ThreadTraits::AutoLock lock(lock_);

    PP_DCHECK(object_);  // Expects a non-null object!
    CallbackData<Dispatcher>* data =
        new CallbackData<Dispatcher>(back_pointer_, dispatcher);

    return Callback(&CallbackData<Dispatcher>::Thunk,
                    data,
                    data->dispatcher()->output());
  }

  // Disallowed:
  CompletionCallbackFactory(const CompletionCallbackFactory&);
  CompletionCallbackFactory& operator=(const CompletionCallbackFactory&);

  // Never changed once initialized so does not need protection by the lock.
  T* object_;

  // Protects the back pointer.
  typename ThreadTraits::Lock lock_;

  // Protected by the lock. This will get reset when you do CancelAll, for
  // example.
  BackPointer* back_pointer_;
};

}  // namespace pp

#endif  // PPAPI_UTILITY_COMPLETION_CALLBACK_FACTORY_H_