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/template_util.h"
   9 #include "gin/converter.h"
  10 #include "gin/gin_export.h"
  11 #include "gin/public/wrapper_info.h"
  12
  13 namespace gin {
  14
  15 namespace internal {
  16
  17 GIN_EXPORT void* FromV8Impl(v8::Isolate* isolate,
  18                             v8::Local<v8::Value> val,
  19                             WrapperInfo* info);
  20
  21 }  // namespace internal
  22
  23
  24 // Wrappable is a base class for C++ objects that have corresponding v8 wrapper
  25 // objects. To retain a Wrappable object on the stack, use a gin::Handle.
  26 //
  27 // USAGE:
  28 // // my_class.h
  29 // class MyClass : Wrappable<MyClass> {
  30 //  public:
  31 //   static WrapperInfo kWrapperInfo;
  32 //
  33 //   // Optional, only required if non-empty template should be used.
  34 //   virtual gin::ObjectTemplateBuilder GetObjectTemplateBuilder(
  35 //       v8::Isolate* isolate);
  36 //   ...
  37 // };
  38 //
  39 // // my_class.cc
  40 // WrapperInfo MyClass::kWrapperInfo = {kEmbedderNativeGin};
  41 //
  42 // gin::ObjectTemplateBuilder MyClass::GetObjectTemplateBuilder(
  43 //     v8::Isolate* isolate) {
  44 //   return Wrappable<MyClass>::GetObjectTemplateBuilder(isolate)
  45 //       .SetValue("foobar", 42);
  46 // }
  47 //
  48 // Subclasses should also typically have private constructors and expose a
  49 // static Create function that returns a gin::Handle. Forcing creators through
  50 // this static Create function will enforce that clients actually create a
  51 // wrapper for the object. If clients fail to create a wrapper for a wrappable
  52 // object, the object will leak because we use the weak callback from the
  53 // wrapper as the signal to delete the wrapped object.
  54 template<typename T>
  55 class Wrappable;
  56
  57 class ObjectTemplateBuilder;
  58
  59 // Non-template base class to share code between templates instances.
  60 class GIN_EXPORT WrappableBase {
  61  protected:
  62   WrappableBase();
  63   virtual ~WrappableBase();
  64
  65   virtual ObjectTemplateBuilder GetObjectTemplateBuilder(v8::Isolate* isolate);
  66
  67   v8::Local<v8::Object> GetWrapperImpl(v8::Isolate* isolate,
  68                                         WrapperInfo* wrapper_info);
  69
  70  private:
  71   static void FirstWeakCallback(
  72       const v8::WeakCallbackInfo<WrappableBase>& data);
  73   static void SecondWeakCallback(
  74       const v8::WeakCallbackInfo<WrappableBase>& data);
  75
  76   v8::Global<v8::Object> wrapper_;  // Weak
  77
  78   DISALLOW_COPY_AND_ASSIGN(WrappableBase);
  79 };
  80
  81
  82 template<typename T>
  83 class Wrappable : public WrappableBase {
  84  public:
  85   // Retrieve (or create) the v8 wrapper object cooresponding to this object.
  86   // To customize the wrapper created for a subclass, override GetWrapperInfo()
  87   // instead of overriding this function.
  88   v8::Local<v8::Object> GetWrapper(v8::Isolate* isolate) {
  89     return GetWrapperImpl(isolate, &T::kWrapperInfo);
  90   }
  91
  92  protected:
  93   Wrappable() {}
  94   virtual ~Wrappable() {}
  95
  96  private:
  97   DISALLOW_COPY_AND_ASSIGN(Wrappable);
  98 };
  99
 100
 101 // This converter handles any subclass of Wrappable.
 102 template<typename T>
 103 struct Converter<T*, typename base::enable_if<
 104                        base::is_convertible<T*, WrappableBase*>::value>::type> {
 105   static v8::Local<v8::Value> ToV8(v8::Isolate* isolate, T* val) {
 106     return val->GetWrapper(isolate);
 107   }
 108
 109   static bool FromV8(v8::Isolate* isolate, v8::Local<v8::Value> val, T** out) {
 110     *out = static_cast<T*>(static_cast<WrappableBase*>(
 111         internal::FromV8Impl(isolate, val, &T::kWrapperInfo)));
 112     return *out != NULL;
 113   }
 114 };
 115
 116 }  // namespace gin
 117
 118 #endif  // GIN_WRAPPABLE_H_