native_client_sdk/doc_generated/pepper_stable/cpp/classpp_1_1_instance_handle.html

{{+bindTo:partials.standard_nacl_api}}
<h1>pp::InstanceHandle Class Reference</h1>
<div id="doxygen-ref">
{{- dummy div to appease doxygen -}}
  <div>
<!-- Generated by Doxygen 1.7.6.1 -->



</div>
<!--header-->
<div class="contents">
<!-- doxytag: class="pp::InstanceHandle" -->
<p><a href="classpp_1_1_instance_handle-members.html">List of all members.</a></p>
<h2>
Public Member Functions</h2><table class="memberdecls">

<tr><td class="memItemLeft" align="right" valign="top">&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classpp_1_1_instance_handle.html#aa9e22c3dc382054c2f3dd816396348dc">InstanceHandle</a> (<a class="el" href="classpp_1_1_instance.html">Instance</a> *instance)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classpp_1_1_instance_handle.html#a9f001cc657a9b9b9307dfa5b20d31856">InstanceHandle</a> (PP_Instance <a class="el" href="classpp_1_1_instance_handle.html#ac413eef4320841121cae58be977d1f7d">pp_instance</a>)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">PP_Instance&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classpp_1_1_instance_handle.html#ac413eef4320841121cae58be977d1f7d">pp_instance</a> () const </td></tr>
</table>
<hr /><a name="details" id="details"></a><h2>Detailed Description</h2>
<div class="textblock"><p>An instance handle identifies an instance in a constructor for a resource. </p>
<p>This class solves two different problems:</p>
<p>1. A <a class="el" href="classpp_1_1_instance.html">pp::Instance</a> 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><a class="el" href="classpp_1_1_instance.html">pp::Instance</a></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.</p>
<p>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><a class="el" href="classpp_1_1_instance.html">pp::Instance</a>*</code> for prettier code on the main thread (you can just pass "this" to resource constructors in your instance objects).</p>
<p>You should always pass an <code><a class="el" href="classpp_1_1_instance_handle.html" title="An instance handle identifies an instance in a constructor for a resource.">InstanceHandle</a></code> to background threads instead of a <code><a class="el" href="classpp_1_1_instance.html">pp::Instance</a></code>, and use them in resource constructors and code that may be used from background threads. </p>
</div><hr /><h2>Constructor &amp; Destructor Documentation</h2>
<a class="anchor" id="aa9e22c3dc382054c2f3dd816396348dc"></a><!-- doxytag: member="pp::InstanceHandle::InstanceHandle" ref="aa9e22c3dc382054c2f3dd816396348dc" args="(Instance *instance)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname"><a class="el" href="classpp_1_1_instance_handle.html#aa9e22c3dc382054c2f3dd816396348dc">pp::InstanceHandle::InstanceHandle</a> </td>
<td>(</td>
<td class="paramtype"><a class="el" href="classpp_1_1_instance.html">Instance</a> *&#160;</td>
<td class="paramname"><em>instance</em></td><td>)</td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Implicit constructor for converting a <code><a class="el" href="classpp_1_1_instance.html">pp::Instance</a></code> to an instance handle. </p>
<dl class="params"><dt><b>Parameters:</b></dt><dd>
<table class="params">
<tr><td class="paramdir">[in]</td><td class="paramname">instance</td><td>The instance with which this <code><a class="el" href="classpp_1_1_instance_handle.html" title="An instance handle identifies an instance in a constructor for a resource.">InstanceHandle</a></code> will be associated. </td></tr>
</table>
</dd>
</dl>
</div>
</div>
<a class="anchor" id="a9f001cc657a9b9b9307dfa5b20d31856"></a><!-- doxytag: member="pp::InstanceHandle::InstanceHandle" ref="a9f001cc657a9b9b9307dfa5b20d31856" args="(PP_Instance pp_instance)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname"><a class="el" href="classpp_1_1_instance_handle.html#aa9e22c3dc382054c2f3dd816396348dc">pp::InstanceHandle::InstanceHandle</a> </td>
<td>(</td>
<td class="paramtype">PP_Instance&#160;</td>
<td class="paramname"><em>pp_instance</em></td><td>)</td>
<td><code> [inline, explicit]</code></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>This constructor explicitly converts a <code>PP_Instance</code> to an instance handle. </p>
<p>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.</p>
<dl class="params"><dt><b>Parameters:</b></dt><dd>
<table class="params">
<tr><td class="paramdir">[in]</td><td class="paramname">pp_instance</td><td>The instance with which this <code><a class="el" href="classpp_1_1_instance_handle.html" title="An instance handle identifies an instance in a constructor for a resource.">InstanceHandle</a></code> will be associated. </td></tr>
</table>
</dd>
</dl>
</div>
</div>
<hr /><h2>Member Function Documentation</h2>
<a class="anchor" id="ac413eef4320841121cae58be977d1f7d"></a><!-- doxytag: member="pp::InstanceHandle::pp_instance" ref="ac413eef4320841121cae58be977d1f7d" args="() const " -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">PP_Instance <a class="el" href="classpp_1_1_instance_handle.html#ac413eef4320841121cae58be977d1f7d">pp::InstanceHandle::pp_instance</a> </td>
<td>(</td>
<td class="paramname"></td><td>)</td>
<td> const<code> [inline]</code></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>The <a class="el" href="classpp_1_1_instance_handle.html#ac413eef4320841121cae58be977d1f7d" title="The pp_instance() function returns the PP_Instance.">pp_instance()</a> function returns the <code>PP_Instance</code>. </p>
<dl class="return"><dt><b>Returns:</b></dt><dd>A <code>PP_Instance</code> internal instance handle. </dd></dl>
</div>
</div>
<hr />The documentation for this class was generated from the following file:<ul>
<li><a class="el" href="instance__handle_8h.html">instance_handle.h</a></li>
</ul>
</div><!-- contents -->
</div>
{{/partials.standard_nacl_api}}