ppapi/cpp/instance_handle.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_CPP_INSTANCE_HANDLE_H_
#define PPAPI_CPP_INSTANCE_HANDLE_H_

#include "ppapi/c/pp_instance.h"


/// @file
/// This file defines an instance handle used to identify an instance in a
/// constructor for a resource.
namespace pp {

class Instance;

/// An instance handle identifies an instance in a constructor for a resource.
/// This class solves two different problems:
///
/// 1. A pp::Instance object's lifetime is managed by the system on the main
/// pepper thread of the module. This means that it may get destroyed at any
/// time based on something that happens on the web page. Therefore, it's not
/// safe to refer to a <code>pp::Instance</code> object on a background thread.
/// Instead, we need to pass some kind of identifier to resource constructors
/// so that they may safely be used on background threads. If the instance
/// becomes invalid, the resource creation will fail on the background thread,
/// but it won't crash.
///
/// 2. <code>PP_Instance</code> would be a good identifier to use for this case.
/// However, using <code>PP_Instance</code> in the constructor to resources is
/// problematic because it is just a typedef for an integer, as is a
/// <code>PP_Resource</code>. Many resources have alternate constructors that
/// just take an existing <code>PP_Resource</code>, so the constructors would
/// be ambiguous. Having this wrapper around a <code>PP_Instance</code>
/// prevents this ambiguity, and also provides a nice place to consolidate an
/// implicit conversion from <code>pp::Instance*</code> for prettier code on
/// the main thread (you can just pass "this" to resource constructors in your
/// instance objects).
///
/// You should always pass an <code>InstanceHandle</code> to background threads
/// instead of a <code>pp::Instance</code>, and use them in resource
/// constructors and code that may be used from background threads.
class InstanceHandle {
 public:
  /// Implicit constructor for converting a <code>pp::Instance</code> to an
  /// instance handle.
  ///
  /// @param[in] instance The instance with which this
  /// <code>InstanceHandle</code> will be associated.
  InstanceHandle(Instance* instance);

  /// This constructor explicitly converts a <code>PP_Instance</code> to an
  /// instance handle. This should not be implicit because it can make some
  /// resource constructors ambiguous. <code>PP_Instance</code> is just a
  /// typedef for an integer, as is <code>PP_Resource</code>, so the compiler
  /// can get confused between the two.
  ///
  /// @param[in] pp_instance The instance with which this
  /// <code>InstanceHandle</code> will be associated.
  explicit InstanceHandle(PP_Instance pp_instance)
      : pp_instance_(pp_instance) {}

  /// The pp_instance() function returns the <code>PP_Instance</code>.
  ///
  /// @return A <code>PP_Instance</code> internal instance handle.
  PP_Instance pp_instance() const { return pp_instance_; }

 private:
  PP_Instance pp_instance_;
};

}  // namespace pp

#endif  // PPAPI_CPP_INSTANCE_HANDLE_H_