// 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_