Struct v8::FunctionTemplate

#[repr(C)]
pub struct FunctionTemplate(/* private fields */);

A FunctionTemplate is used to create functions at runtime. There can only be one function created from a FunctionTemplate in a context. The lifetime of the created function is equal to the lifetime of the context. So in case the embedder needs to create temporary functions that can be collected using Scripts is preferred.

Any modification of a FunctionTemplate after first instantiation will trigger a crash.

A FunctionTemplate can have properties, these properties are added to the function object when it is created.

A FunctionTemplate has a corresponding instance template which is used to create object instances when the function is used as a constructor. Properties added to the instance template are added to each object instance.

A FunctionTemplate can have a prototype template. The prototype template is used to create the prototype object of the function.

The following example shows how to use a FunctionTemplate:

   v8::Local<v8::FunctionTemplate> t = v8::FunctionTemplate::New(isolate);
   t->Set(isolate, "func_property", v8::Number::New(isolate, 1));

   v8::Local<v8::Template> proto_t = t->PrototypeTemplate();
   proto_t->Set(isolate,
                "proto_method",
                v8::FunctionTemplate::New(isolate, InvokeCallback));
   proto_t->Set(isolate, "proto_const", v8::Number::New(isolate, 2));

   v8::Local<v8::ObjectTemplate> instance_t = t->InstanceTemplate();
   instance_t->SetAccessor(
       String::NewFromUtf8Literal(isolate, "instance_accessor"),
       InstanceAccessorCallback);
   instance_t->SetHandler(
       NamedPropertyHandlerConfiguration(PropertyHandlerCallback));
   instance_t->Set(String::NewFromUtf8Literal(isolate, "instance_property"),
                   Number::New(isolate, 3));

   v8::Local<v8::Function> function = t->GetFunction();
   v8::Local<v8::Object> instance = function->NewInstance();

Let’s use “function” as the JS variable name of the function object and “instance” for the instance object created above. The function and the instance will have the following properties:

  func_property in function == true;
  function.func_property == 1;

  function.prototype.proto_method() invokes 'InvokeCallback'
  function.prototype.proto_const == 2;

  instance instanceof function == true;
  instance.instance_accessor calls 'InstanceAccessorCallback'
  instance.instance_property == 3;

A FunctionTemplate can inherit from another one by calling the FunctionTemplate::Inherit method. The following graph illustrates the semantics of inheritance:

  FunctionTemplate Parent  -> Parent() . prototype -> { }
    ^                                                  ^
    | Inherit(Parent)                                  | .__proto__
    |                                                  |
  FunctionTemplate Child   -> Child()  . prototype -> { }

A FunctionTemplate ‘Child’ inherits from ‘Parent’, the prototype object of the Child() function has proto pointing to the Parent() function’s prototype object. An instance of the Child function has all properties on Parent’s instance templates.

Let Parent be the FunctionTemplate initialized in the previous section and create a Child FunctionTemplate by:

  Local<FunctionTemplate> parent = t;
  Local<FunctionTemplate> child = FunctionTemplate::New();
  child->Inherit(parent);

  Local<Function> child_function = child->GetFunction();
  Local<Object> child_instance = child_function->NewInstance();

The Child function and Child instance will have the following properties:

  child_func.prototype.__proto__ == function.prototype;
  child_instance.instance_accessor calls 'InstanceAccessorCallback'
  child_instance.instance_property == 3;

The additional ‘c_function’ parameter refers to a fast API call, which must not trigger GC or JavaScript execution, or call into V8 in other ways. For more information how to define them, see include/v8-fast-api-calls.h. Please note that this feature is still experimental.

Implementations

impl FunctionTemplate

pub fn builder<'s>( callback: impl MapFnTo<FunctionCallback> ) -> FunctionBuilder<'s, Self>

Create a FunctionBuilder to configure a FunctionTemplate. This is the same as FunctionBuilder::::new().

pub fn builder_raw<'s>(callback: FunctionCallback) -> FunctionBuilder<'s, Self>

pub fn new<'s>( scope: &mut HandleScope<'s, ()>, callback: impl MapFnTo<FunctionCallback> ) -> Local<'s, FunctionTemplate>

Creates a function template.

pub fn new_raw<'s>( scope: &mut HandleScope<'s, ()>, callback: FunctionCallback ) -> Local<'s, FunctionTemplate>

pub fn get_function<'s>( &self, scope: &mut HandleScope<'s> ) -> Option<Local<'s, Function>>

Returns the unique function instance in the current execution context.

pub fn set_class_name(&self, name: Local<'_, String>)

Set the class name of the FunctionTemplate. This is used for printing objects created with the function created from the FunctionTemplate as its constructor.

pub fn prototype_template<'s>( &self, scope: &mut HandleScope<'s, ()> ) -> Local<'s, ObjectTemplate>

Returns the ObjectTemplate that is used by this FunctionTemplate as a PrototypeTemplate

pub fn instance_template<'s>( &self, scope: &mut HandleScope<'s, ()> ) -> Local<'s, ObjectTemplate>

Returns the object template that is used for instances created when this function template is called as a constructor.

pub fn inherit(&self, parent: Local<'_, FunctionTemplate>)

Causes the function template to inherit from a parent function template. This means the function’s prototype.proto is set to the parent function’s prototype.

pub fn read_only_prototype(&self)

Sets the ReadOnly flag in the attributes of the ‘prototype’ property of functions created from this FunctionTemplate to true.

pub fn remove_prototype(&self)

Removes the prototype property from functions created from this FunctionTemplate.

Methods from Deref<Target = Template>

pub fn set(&self, key: Local<'_, Name>, value: Local<'_, Data>)

Adds a property to each instance created by this template.

pub fn set_with_attr( &self, key: Local<'_, Name>, value: Local<'_, Data>, attr: PropertyAttribute )

Adds a property to each instance created by this template with the specified property attributes.

Methods from Deref<Target = Data>

pub fn is_big_int(&self) -> bool

Returns true if this data is a BigInt.

pub fn is_boolean(&self) -> bool

Returns true if this data is a Boolean.

pub fn is_context(&self) -> bool

Returns true if this data is a Context.

pub fn is_fixed_array(&self) -> bool

Returns true if this data is a FixedArray.

pub fn is_function_template(&self) -> bool

Returns true if this data is a FunctionTemplate.

pub fn is_module(&self) -> bool

Returns true if this data is a Module.

pub fn is_module_request(&self) -> bool

Returns true if this data is a ModuleRequest.

pub fn is_name(&self) -> bool

Returns true if this data is a Name.

pub fn is_number(&self) -> bool

Returns true if this data is a Number.

pub fn is_object_template(&self) -> bool

Returns true if this data is a ObjectTemplate.

pub fn is_primitive(&self) -> bool

Returns true if this data is a Primitive.

pub fn is_private(&self) -> bool

Returns true if this data is a Private.

pub fn is_string(&self) -> bool

Returns true if this data is a String.

pub fn is_symbol(&self) -> bool

Returns true if this data is a Symbol.

pub fn is_value(&self) -> bool

Returns true if this data is a Value.

Trait Implementations

impl Debug for FunctionTemplate

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Deref for FunctionTemplate

type Target = Template

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl<'s> PartialEq<Data> for FunctionTemplate

fn eq(&self, other: &Data) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<'s> PartialEq<FunctionTemplate> for Data

fn eq(&self, other: &FunctionTemplate) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<'s> PartialEq<FunctionTemplate> for Template

fn eq(&self, other: &FunctionTemplate) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<'s> PartialEq<Template> for FunctionTemplate

fn eq(&self, other: &Template) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<'s> PartialEq for FunctionTemplate

fn eq(&self, other: &FunctionTemplate) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Eq for FunctionTemplate