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. 44 class InstanceHandle { 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_ 76
