5644924d7a
Review URL: http://codereview.chromium.org/9815025 git-svn-id: svn://svn.chromium.org/chrome/trunk/src@131594 0039d316-1c4b-4281-b951-d872f2087c98
76 lines
3.1 KiB
C++
76 lines
3.1 KiB
C++
// 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_
|