diff options
Diffstat (limited to 'ppapi')
| -rw-r--r-- | ppapi/cpp/instance_handle.h | 67 | ||||
| -rw-r--r-- | ppapi/cpp/pass_ref.h | 7 |
2 files changed, 47 insertions, 27 deletions
diff --git a/ppapi/cpp/instance_handle.h b/ppapi/cpp/instance_handle.h index 941db6e..fd118fd 100644 --- a/ppapi/cpp/instance_handle.h +++ b/ppapi/cpp/instance_handle.h @@ -7,46 +7,63 @@ #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. -/// Its existence solves two different problems: +/// This class solves two different problems: /// -/// A pp::Instance objects' lifetime is managed by the system on the main thread -/// of the plugin. This means that it may get destroyed at any time based on -/// something that happens on the web page. This means that it's never OK to -/// refer to a pp::Instance object on a background thread. So we need to pass -/// some kind of identifier instead 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. +/// 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. /// -/// Background: PP_Instance would be a good identifier to use for this case. -/// However, using it in the constructor to resources is problematic. -/// PP_Instance is just a typedef for an integer, as is a PP_Resource. Many -/// resources have alternate constructors that just take an existing -/// PP_Resource, so the constructors would be ambiguous. Having this wrapper -/// around a PP_Instance prevents this ambiguity, and also gives us a nice -/// place to consolidate an implicit conversion from pp::Instance* for prettier -/// code on the main thread (you can just pass "this" to resource constructors -/// in your instance objects). +/// 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). /// -/// So you should always pass InstanceHandles to background threads instead of -/// a pp::Instance, and use them in resource constructors and code that may be -/// used from background threads. +/// 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 pp::Instance to an instance handle. + /// 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); - /// Explicitly convert a PP_Instance to an instance handle. This should not - /// be implicit because it can make some resource constructors ambiguous. - /// PP_Instance is just a typedef for an integer, as is PP_Resource, so the - /// compiler can get confused between the two. + /// 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: diff --git a/ppapi/cpp/pass_ref.h b/ppapi/cpp/pass_ref.h index ebe1ddd..7248674 100644 --- a/ppapi/cpp/pass_ref.h +++ b/ppapi/cpp/pass_ref.h @@ -5,12 +5,15 @@ #ifndef PPAPI_CPP_PASS_REF_H_ #define PPAPI_CPP_PASS_REF_H_ +/// @file +/// This file defines an annotation for constructors and other functions that +/// take ownership of a pointer. namespace pp { /// An annotation for constructors and other functions that take ownership of /// a pointer. For example, a resource constructor that takes ownership of a -/// passed in PP_Resource ref count would take this to differentiate from -/// the more typical use case of taking its own ref. +/// provided <code>PP_Resource</code> ref count would take this enumeration to +/// differentiate from the more typical use case of taking its own reference. enum PassRef { PASS_REF }; } // namespace pp |