gin/wrappable.h

   1 // Copyright 2013 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 GIN_WRAPPABLE_H_
   6 #define GIN_WRAPPABLE_H_
   7
   8 #include "base/memory/ref_counted.h"
   9 #include "gin/converter.h"
  10 #include "gin/public/wrapper_info.h"
  11
  12 namespace gin {
  13
  14 // Wrappable is an abstract base class for C++ objects that have cooresponding
  15 // v8 wrapper objects. Wrappable are RefCounted, which means they can be
  16 // retained either by V8's garbage collector or by a scoped_refptr.
  17 //
  18 // WARNING: If you retain a Wrappable object with a scoped_refptr, it's possible
  19 //          that the v8 wrapper can "fall off" if the wrapper object is not
  20 //          referenced elsewhere in the V8 heap. Although Wrappable opens a
  21 //          handle to the wrapper object, we make that handle as weak, which
  22 //          means V8 is free to reclaim the wrapper. (We can't make the handle
  23 //          strong without risking introducing a memory leak if an object that
  24 //          holds a scoped_refptr is reachable from the wrapper.)
  25 //
  26 class Wrappable : public base::RefCounted<Wrappable> {
  27  public:
  28   // Subclasses must return the WrapperInfo object associated with the
  29   // v8::ObjectTemplate for their subclass. When creating a v8 wrapper for
  30   // this object, we'll look up the appropriate v8::ObjectTemplate in the
  31   // PerIsolateData using this WrapperInfo pointer.
  32   virtual WrapperInfo* GetWrapperInfo() = 0;
  33
  34   // Subclasses much also contain a static member variable named |kWrapperInfo|
  35   // of type WrapperInfo:
  36   //
  37   //   static WrapperInfo kWrapperInfo;
  38   //
  39   // If |obj| is a concrete instance of the subclass, then obj->GetWrapperInfo()
  40   // must return &kWrapperInfo.
  41   //
  42   // We use both the dynamic |GetWrapperInfo| function and the static
  43   // |kWrapperInfo| member variable during wrapping and the unwrapping. During
  44   // wrapping, we use GetWrapperInfo() to make sure we use the correct
  45   // v8::ObjectTemplate for the object regardless of the declared C++ type.
  46   // During unwrapping, we use the static member variable to prevent type errors
  47   // during the downcast from Wrappable to the subclass.
  48
  49   // Retrieve (or create) the v8 wrapper object cooresponding to this object.
  50   // To customize the wrapper created for a subclass, override GetWrapperInfo()
  51   // instead of overriding this function.
  52   v8::Handle<v8::Object> GetWrapper(v8::Isolate* isolate);
  53
  54  protected:
  55   Wrappable();
  56   virtual ~Wrappable();
  57
  58  private:
  59   friend class base::RefCounted<Wrappable>;
  60   friend struct Converter<Wrappable*>;
  61
  62   static void WeakCallback(
  63       const v8::WeakCallbackData<v8::Object, Wrappable>& data);
  64   v8::Handle<v8::Object> CreateWrapper(v8::Isolate* isolate);
  65
  66   v8::Persistent<v8::Object> wrapper_;  // Weak
  67
  68   DISALLOW_COPY_AND_ASSIGN(Wrappable);
  69 };
  70
  71 template<>
  72 struct Converter<Wrappable*> {
  73   static v8::Handle<v8::Value> ToV8(v8::Isolate* isolate,
  74                                     Wrappable* val);
  75   static bool FromV8(v8::Isolate* isolate, v8::Handle<v8::Value> val,
  76                      Wrappable** out);
  77 };
  78
  79 template<typename T>
  80 struct WrappableConverter {
  81   static v8::Handle<v8::Value> ToV8(v8::Isolate* isolate, T* val) {
  82     return Converter<Wrappable*>::ToV8(isolate, val);
  83   }
  84   static bool FromV8(v8::Isolate* isolate, v8::Handle<v8::Value> val, T** out) {
  85     Wrappable* wrappable = 0;
  86     if (!Converter<Wrappable*>::FromV8(isolate, val, &wrappable)
  87         || wrappable->GetWrapperInfo() != &T::kWrapperInfo)
  88       return false;
  89     // Currently we require that you unwrap to the exact runtime type of the
  90     // wrapped object.
  91     // TODO(abarth): Support unwrapping to a base class.
  92     *out = static_cast<T*>(wrappable);
  93     return true;
  94   }
  95 };
  96
  97 }  // namespace gin
  98
  99 #endif  // GIN_WRAPPABLE_H_