Pepper_31_C++_interfaces
instance_handle.h
Go to the documentation of this file.
1 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
2 // Use of this source code is governed by a BSD-style license that can be
3 // found in the LICENSE file.
4 
5 #ifndef PPAPI_CPP_INSTANCE_HANDLE_H_
6 #define PPAPI_CPP_INSTANCE_HANDLE_H_
7 
8 #include "ppapi/c/pp_instance.h"
9 
10 
11 /// @file
12 /// This file defines an instance handle used to identify an instance in a
13 /// constructor for a resource.
14 namespace pp {
15 
16 class Instance;
17 
18 /// An instance handle identifies an instance in a constructor for a resource.
19 /// This class solves two different problems:
20 ///
21 /// 1. A pp::Instance object's lifetime is managed by the system on the main
22 /// pepper thread of the module. This means that it may get destroyed at any
23 /// time based on something that happens on the web page. Therefore, it's not
24 /// safe to refer to a <code>pp::Instance</code> object on a background thread.
25 /// Instead, we need to pass some kind of identifier to resource constructors
26 /// so that they may safely be used on background threads. If the instance
27 /// becomes invalid, the resource creation will fail on the background thread,
28 /// but it won't crash.
29 ///
30 /// 2. <code>PP_Instance</code> would be a good identifier to use for this case.
31 /// However, using <code>PP_Instance</code> in the constructor to resources is
32 /// problematic because it is just a typedef for an integer, as is a
33 /// <code>PP_Resource</code>. Many resources have alternate constructors that
34 /// just take an existing <code>PP_Resource</code>, so the constructors would
35 /// be ambiguous. Having this wrapper around a <code>PP_Instance</code>
36 /// prevents this ambiguity, and also provides a nice place to consolidate an
37 /// implicit conversion from <code>pp::Instance*</code> for prettier code on
38 /// the main thread (you can just pass "this" to resource constructors in your
39 /// instance objects).
40 ///
41 /// You should always pass an <code>InstanceHandle</code> to background threads
42 /// instead of a <code>pp::Instance</code>, and use them in resource
43 /// constructors and code that may be used from background threads.
45  public:
46  /// Implicit constructor for converting a <code>pp::Instance</code> to an
47  /// instance handle.
48  ///
49  /// @param[in] instance The instance with which this
50  /// <code>InstanceHandle</code> will be associated.
51  InstanceHandle(Instance* instance);
52 
53  /// This constructor explicitly converts a <code>PP_Instance</code> to an
54  /// instance handle. This should not be implicit because it can make some
55  /// resource constructors ambiguous. <code>PP_Instance</code> is just a
56  /// typedef for an integer, as is <code>PP_Resource</code>, so the compiler
57  /// can get confused between the two.
58  ///
59  /// @param[in] pp_instance The instance with which this
60  /// <code>InstanceHandle</code> will be associated.
61  explicit InstanceHandle(PP_Instance pp_instance)
62  : pp_instance_(pp_instance) {}
63 
64  /// The pp_instance() function returns the <code>PP_Instance</code>.
65  ///
66  /// @return A <code>PP_Instance</code> internal instance handle.
67  PP_Instance pp_instance() const { return pp_instance_; }
68 
69  private:
70  PP_Instance pp_instance_;
71 };
72 
73 } // namespace pp
74 
75 #endif // PPAPI_CPP_INSTANCE_HANDLE_H_
InstanceHandle(Instance *instance)
InstanceHandle(PP_Instance pp_instance)
PP_Instance pp_instance() const