ppapi/cpp/instance_handle.h

   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_