src/ppapi/shared_impl/var_tracker.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_SHARED_IMPL_VAR_TRACKER_H_
   6 #define PPAPI_SHARED_IMPL_VAR_TRACKER_H_
   7
   8 #include <vector>
   9
  10 #include "base/basictypes.h"
  11 #include "base/containers/hash_tables.h"
  12 #include "base/memory/ref_counted.h"
  13 #include "base/memory/scoped_ptr.h"
  14 #include "base/memory/shared_memory.h"
  15 #include "base/threading/thread_checker.h"
  16 #include "ppapi/c/pp_instance.h"
  17 #include "ppapi/c/pp_module.h"
  18 #include "ppapi/c/pp_resource.h"
  19 #include "ppapi/c/pp_var.h"
  20 #include "ppapi/shared_impl/host_resource.h"
  21 #include "ppapi/shared_impl/ppapi_shared_export.h"
  22 #include "ppapi/shared_impl/var.h"
  23
  24 namespace IPC {
  25 class Message;
  26 }  // namespace IPC
  27
  28 namespace ppapi {
  29
  30 class ArrayBufferVar;
  31
  32 // Tracks non-POD (refcounted) var objects held by a plugin.
  33 //
  34 // The tricky part is the concept of a "tracked object". These are only
  35 // necessary in the plugin side of the proxy when running out of process. A
  36 // tracked object is one that the plugin is aware of, but doesn't hold a
  37 // reference to. This will happen when the plugin is passed an object as an
  38 // argument from the host (renderer) as an input argument to a sync function,
  39 // but where ownership is not passed.
  40 //
  41 // This class maintains the "track_with_no_reference_count" but doesn't do
  42 // anything with it other than call virtual functions. The interesting parts
  43 // are added by the PluginObjectVar derived from this class.
  44 class PPAPI_SHARED_EXPORT VarTracker {
  45  public:
  46   // A SINGLE_THREADED VarTracker will use a thread-checker to make sure it's
  47   // always invoked on the same thread on which it was constructed. A
  48   // THREAD_SAFE VarTracker will check that the ProxyLock is held. See
  49   // CheckThreadingPreconditions() for more details.
  50   enum ThreadMode { SINGLE_THREADED, THREAD_SAFE };
  51   explicit VarTracker(ThreadMode thread_mode);
  52   virtual ~VarTracker();
  53
  54   // Called by the Var object to add a new var to the tracker.
  55   int32 AddVar(Var* var);
  56
  57   // Looks up a given var and returns a reference to the Var if it exists.
  58   // Returns NULL if the var type is not an object we track (POD) or is
  59   // invalid.
  60   Var* GetVar(int32 var_id) const;
  61   Var* GetVar(const PP_Var& var) const;
  62
  63   // Increases a previously-known Var ID's refcount, returning true on success,
  64   // false if the ID is invalid. The PP_Var version returns true and does
  65   // nothing for non-refcounted type vars.
  66   bool AddRefVar(int32 var_id);
  67   bool AddRefVar(const PP_Var& var);
  68
  69   // Decreases the given Var ID's refcount, returning true on success, false if
  70   // the ID is invalid or if the refcount was already 0. The PP_Var version
  71   // returns true and does nothing for non-refcounted type vars. The var will
  72   // be deleted if there are no more refs to it.
  73   bool ReleaseVar(int32 var_id);
  74   bool ReleaseVar(const PP_Var& var);
  75
  76   // Create a new array buffer of size |size_in_bytes|. Return a PP_Var that
  77   // that references it and has an initial reference-count of 1.
  78   PP_Var MakeArrayBufferPPVar(uint32 size_in_bytes);
  79   // Same as above, but copy the contents of |data| in to the new array buffer.
  80   PP_Var MakeArrayBufferPPVar(uint32 size_in_bytes, const void* data);
  81   // Same as above, but copy the contents of the shared memory in |h|
  82   // into the new array buffer.
  83   PP_Var MakeArrayBufferPPVar(uint32 size_in_bytes,
  84                               base::SharedMemoryHandle h);
  85
  86   // Create an ArrayBuffer and copy the contents of |data| in to it. The
  87   // returned object has 0 reference count in the tracker, and like all
  88   // RefCounted objects, has a 0 initial internal reference count. (You should
  89   // usually immediately put this in a scoped_refptr).
  90   ArrayBufferVar* MakeArrayBufferVar(uint32 size_in_bytes, const void* data);
  91
  92   // Creates a new resource var from a resource creation message. Returns a
  93   // PP_Var that references a new PP_Resource, both with an initial reference
  94   // count of 1. On the host side, |creation_message| is ignored, and an empty
  95   // resource var is always returned.
  96   virtual PP_Var MakeResourcePPVarFromMessage(
  97       PP_Instance instance,
  98       const IPC::Message& creation_message,
  99       int pending_renderer_id,
 100       int pending_browser_id) = 0;
 101
 102   // Creates a new resource var that points to a given resource ID. Returns a
 103   // PP_Var that references it and has an initial reference count of 1.
 104   // If |pp_resource| is 0, returns a valid, empty resource var. On the plugin
 105   // side (where it is possible to tell which resources exist), if |pp_resource|
 106   // does not exist, returns a null var.
 107   PP_Var MakeResourcePPVar(PP_Resource pp_resource);
 108
 109   // Creates a new resource var that points to a given resource ID. This is
 110   // implemented by the host and plugin tracker separately, because the plugin
 111   // keeps a reference to the resource, and the host does not.
 112   // If |pp_resource| is 0, returns a valid, empty resource var. On the plugin
 113   // side (where it is possible to tell which resources exist), if |pp_resource|
 114   // does not exist, returns NULL.
 115   virtual ResourceVar* MakeResourceVar(PP_Resource pp_resource) = 0;
 116
 117   // Return a vector containing all PP_Vars that are in the tracker. This is
 118   // to help implement PPB_Testing_Dev.GetLiveVars and should generally not be
 119   // used in production code. The PP_Vars are returned in no particular order,
 120   // and their reference counts are unaffected.
 121   std::vector<PP_Var> GetLiveVars();
 122
 123   // Retrieves the internal reference counts for testing. Returns 0 if we
 124   // know about the object but the corresponding value is 0, or -1 if the
 125   // given object ID isn't in our map.
 126   int GetRefCountForObject(const PP_Var& object);
 127   int GetTrackedWithNoReferenceCountForObject(const PP_Var& object);
 128
 129   // Returns true if the given vartype is refcounted and has associated objects
 130   // (it's not POD).
 131   static bool IsVarTypeRefcounted(PP_VarType type);
 132
 133   // Called after an instance is deleted to do var cleanup.
 134   virtual void DidDeleteInstance(PP_Instance instance) = 0;
 135
 136   // Returns an "id" for a shared memory handle that can be safely sent between
 137   // the host and plugin, and resolved back into the original handle on the
 138   // host. Not implemented on the plugin side.
 139   virtual int TrackSharedMemoryHandle(PP_Instance instance,
 140                                       base::SharedMemoryHandle handle,
 141                                       uint32 size_in_bytes) = 0;
 142
 143   // Resolves an "id" generated by TrackSharedMemoryHandle back into
 144   // a SharedMemory handle and its size on the host.
 145   // Not implemented on the plugin side.
 146   virtual bool StopTrackingSharedMemoryHandle(
 147       int id,
 148       PP_Instance instance,
 149       base::SharedMemoryHandle *handle,
 150       uint32* size_in_bytes) = 0;
 151
 152  protected:
 153   struct PPAPI_SHARED_EXPORT VarInfo {
 154     VarInfo();
 155     VarInfo(Var* v, int input_ref_count);
 156
 157     scoped_refptr<Var> var;
 158
 159     // Explicit reference count. This value is affected by the renderer calling
 160     // AddRef and Release. A nonzero value here is represented by a single
 161     // reference in the host on our behalf (this reduces IPC traffic).
 162     int ref_count;
 163
 164     // Tracked object count (see class comment above).
 165     //
 166     // "TrackObjectWithNoReference" might be called recursively in rare cases.
 167     // For example, say the host calls a plugin function with an object as an
 168     // argument, and in response, the plugin calls a host function that then
 169     // calls another (or the same) plugin function with the same object.
 170     //
 171     // This value tracks the number of calls to TrackObjectWithNoReference so
 172     // we know when we can stop tracking this object.
 173     int track_with_no_reference_count;
 174   };
 175   typedef base::hash_map<int32, VarInfo> VarMap;
 176
 177   // Specifies what should happen with the refcount when calling AddVarInternal.
 178   enum AddVarRefMode {
 179     ADD_VAR_TAKE_ONE_REFERENCE,
 180     ADD_VAR_CREATE_WITH_NO_REFERENCE
 181   };
 182
 183   // On the host-side, make sure we are called on the right thread. On the
 184   // plugin side, make sure we have the proxy lock.
 185   void CheckThreadingPreconditions() const;
 186
 187   // Implementation of AddVar that allows the caller to specify whether the
 188   // initial refcount of the added object will be 0 or 1.
 189   //
 190   // Overridden in the plugin proxy to do additional object tracking.
 191   virtual int32 AddVarInternal(Var* var, AddVarRefMode mode);
 192
 193   // Convenience functions for doing lookups into the live_vars_ map.
 194   VarMap::iterator GetLiveVar(int32 id);
 195   VarMap::iterator GetLiveVar(const PP_Var& var);
 196   VarMap::const_iterator GetLiveVar(const PP_Var& var) const;
 197
 198   // Called when AddRefVar increases a "tracked" ProxyObject's refcount from
 199   // zero to one. In the plugin side of the proxy, we need to send some
 200   // messages to the host. In the host side, this should never be called since
 201   // there are no proxy objects.
 202   virtual void TrackedObjectGettingOneRef(VarMap::const_iterator iter);
 203
 204   // Called when ReleaseVar decreases a object's refcount from one to zero. It
 205   // may still be "tracked" (has a "track_with_no_reference_count") value. In
 206   // the plugin side of the proxy, we need to tell the host that we no longer
 207   // have a reference. In the host side, this should never be called since
 208   // there are no proxy objects.
 209   virtual void ObjectGettingZeroRef(VarMap::iterator iter);
 210
 211   // Called when an object may have had its refcount or
 212   // track_with_no_reference_count value decreased. If the object has neither
 213   // refs anymore, this will remove it and return true. Returns false if it's
 214   // still alive.
 215   //
 216   // Overridden by the PluginVarTracker to also clean up the host info map.
 217   virtual bool DeleteObjectInfoIfNecessary(VarMap::iterator iter);
 218
 219   VarMap live_vars_;
 220
 221   // Last assigned var ID.
 222   int32 last_var_id_;
 223
 224  private:
 225   // Create and return a new ArrayBufferVar size_in_bytes bytes long. This is
 226   // implemented by the Host and Plugin tracker separately, so that it can be
 227   // a real WebKit ArrayBuffer on the host side.
 228   virtual ArrayBufferVar* CreateArrayBuffer(uint32 size_in_bytes) = 0;
 229   virtual ArrayBufferVar* CreateShmArrayBuffer(
 230       uint32 size_in_bytes,
 231       base::SharedMemoryHandle handle) = 0;
 232
 233   // On the host side, we want to check that we are only called on the main
 234   // thread. This is to protect us from accidentally using the tracker from
 235   // other threads (especially the IO thread). On the plugin side, the tracker
 236   // is protected by the proxy lock and is thread-safe, so this will be NULL.
 237   scoped_ptr<base::ThreadChecker> thread_checker_;
 238
 239   DISALLOW_COPY_AND_ASSIGN(VarTracker);
 240 };
 241
 242 }  // namespace ppapi
 243
 244 #endif  // PPAPI_SHARED_IMPL_VAR_TRACKER_H_