How do you expose a C++ class in the V8 Javascript Engine so it can be created using new?

Steve Hanov picture Steve Hanov · Jun 18, 2010 · Viewed 18k times · Source

The official examples of exposing a Point class seem to assume that there will be a fixed number of instances of it in your program. It is not clear how new instances are allocated in the C++ code, when new is called in Javascript.

How would you expose a class that can have multiple instances? For example, an Image class:

var img1 = new Image( 640, 480 );
var img2 = new Image( 1024, 768 );

img1.clear( "red" );
img2.clear( "black" );

Answer

Leftium picture Leftium · Oct 5, 2010

This is the best blog post I could find on exposing C++ objects to V8 Javascript. It goes into deeper detail and breaks it down into smaller steps with code snippets. Be warned: the code snippets have little inconsistencies and it took me several reads to understand. Reading my brief summary beforehand may help:

  1. Objects must be wrapped in V8 templates. Note: The Google sample uses ObjectTemplates, but the author explains why he prefers FunctionTemplates.
    1. Create a FunctionTemplate. Instances of this template have an internal field to store the memory address of the C++ object. They also get the class' accessor methods.
    2. Make a function wrapObject() that will wrap a C++ object in one of these FunctionTemplates.
  2. The constructor must also be wrapped in a (different) V8 template. A different template is used to avoid unwanted recursion. (A method of combining both templates into one is described at the end of the blog post.)
    1. Create another FunctionTemplate. This template simply connects the JavaScript global scope (where new will be called from) to the C++ constructor.
    2. Make the method that the template will call. This method actually uses the C++ new operator and calls the C++ class constructor. It then wraps the object by calling the wrapObject() method created in step 1.2.

Now, the memory allocated in step 2.2 must be delete'd some time. Update: The next blog entry, "Persistent Handles," covers this in detail.

My notes on the actual code alluded to in these blog posts:

  • The wrapPoint() method in the blog is actually analogous to the unwrap() method in the actual code; not wrap()
  • To find other common points between the code, search for: SetInternalFieldCount(0, constructorCall
  • The actual code seems to do memory management by using the MakeWeak() method to set a callback method that does the cleanup.