v8  10.1.124 (node 18.2.0)
V8 is Google's open source JavaScript engine
FunctionTemplate Class Reference

#include <v8-template.h>

Inheritance diagram for FunctionTemplate:
Collaboration diagram for FunctionTemplate:

Public Member Functions

V8_WARN_UNUSED_RESULT MaybeLocal< FunctionGetFunction (Local< Context > context)
 
V8_WARN_UNUSED_RESULT MaybeLocal< ObjectNewRemoteInstance ()
 
void SetCallHandler (FunctionCallback callback, Local< Value > data=Local< Value >(), SideEffectType side_effect_type=SideEffectType::kHasSideEffect, const MemorySpan< const CFunction > &c_function_overloads={})
 
void SetLength (int length)
 
Local< ObjectTemplateInstanceTemplate ()
 
void Inherit (Local< FunctionTemplate > parent)
 
Local< ObjectTemplatePrototypeTemplate ()
 
void SetPrototypeProviderTemplate (Local< FunctionTemplate > prototype_provider)
 
void SetClassName (Local< String > name)
 
void SetAcceptAnyReceiver (bool value)
 
void ReadOnlyPrototype ()
 
void RemovePrototype ()
 
bool HasInstance (Local< Value > object)
 
bool IsLeafTemplateForApiObject (v8::Local< v8::Value > value) const
 
- Public Member Functions inherited from Template
void Set (Local< Name > name, Local< Data > value, PropertyAttribute attributes=None)
 
void SetPrivate (Local< Private > name, Local< Data > value, PropertyAttribute attributes=None)
 
V8_INLINE void Set (Isolate *isolate, const char *name, Local< Data > value, PropertyAttribute attributes=None)
 
void SetAccessorProperty (Local< Name > name, Local< FunctionTemplate > getter=Local< FunctionTemplate >(), Local< FunctionTemplate > setter=Local< FunctionTemplate >(), PropertyAttribute attribute=None, AccessControl settings=DEFAULT)
 
void SetNativeDataProperty (Local< String > name, AccessorGetterCallback getter, AccessorSetterCallback setter=nullptr, Local< Value > data=Local< Value >(), PropertyAttribute attribute=None, Local< AccessorSignature > signature=Local< AccessorSignature >(), AccessControl settings=DEFAULT, SideEffectType getter_side_effect_type=SideEffectType::kHasSideEffect, SideEffectType setter_side_effect_type=SideEffectType::kHasSideEffect)
 
void SetNativeDataProperty (Local< Name > name, AccessorNameGetterCallback getter, AccessorNameSetterCallback setter=nullptr, Local< Value > data=Local< Value >(), PropertyAttribute attribute=None, Local< AccessorSignature > signature=Local< AccessorSignature >(), AccessControl settings=DEFAULT, SideEffectType getter_side_effect_type=SideEffectType::kHasSideEffect, SideEffectType setter_side_effect_type=SideEffectType::kHasSideEffect)
 
void SetLazyDataProperty (Local< Name > name, AccessorNameGetterCallback getter, Local< Value > data=Local< Value >(), PropertyAttribute attribute=None, SideEffectType getter_side_effect_type=SideEffectType::kHasSideEffect, SideEffectType setter_side_effect_type=SideEffectType::kHasSideEffect)
 
void SetIntrinsicDataProperty (Local< Name > name, Intrinsic intrinsic, PropertyAttribute attribute=None)
 
- Public Member Functions inherited from Data
bool IsValue () const
 
bool IsModule () const
 
bool IsFixedArray () const
 
bool IsPrivate () const
 
bool IsObjectTemplate () const
 
bool IsFunctionTemplate () const
 
bool IsContext () const
 

Static Public Member Functions

static Local< FunctionTemplateNew (Isolate *isolate, FunctionCallback callback=nullptr, Local< Value > data=Local< Value >(), Local< Signature > signature=Local< Signature >(), int length=0, ConstructorBehavior behavior=ConstructorBehavior::kAllow, SideEffectType side_effect_type=SideEffectType::kHasSideEffect, const CFunction *c_function=nullptr, uint16_t instance_type=0, uint16_t allowed_receiver_instance_type_range_start=0, uint16_t allowed_receiver_instance_type_range_end=0)
 
static Local< FunctionTemplateNewWithCFunctionOverloads (Isolate *isolate, FunctionCallback callback=nullptr, Local< Value > data=Local< Value >(), Local< Signature > signature=Local< Signature >(), int length=0, ConstructorBehavior behavior=ConstructorBehavior::kAllow, SideEffectType side_effect_type=SideEffectType::kHasSideEffect, const MemorySpan< const CFunction > &c_function_overloads={})
 
static Local< FunctionTemplateNewWithCache (Isolate *isolate, FunctionCallback callback, Local< Private > cache_property, Local< Value > data=Local< Value >(), Local< Signature > signature=Local< Signature >(), int length=0, SideEffectType side_effect_type=SideEffectType::kHasSideEffect)
 
static V8_INLINE FunctionTemplateCast (Data *data)
 

Friends

class Context
 
class ObjectTemplate
 

Detailed Description

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:

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();
static Local< FunctionTemplate > New(Isolate *isolate, FunctionCallback callback=nullptr, Local< Value > data=Local< Value >(), Local< Signature > signature=Local< Signature >(), int length=0, ConstructorBehavior behavior=ConstructorBehavior::kAllow, SideEffectType side_effect_type=SideEffectType::kHasSideEffect, const CFunction *c_function=nullptr, uint16_t instance_type=0, uint16_t allowed_receiver_instance_type_range_start=0, uint16_t allowed_receiver_instance_type_range_end=0)
static Local< Number > New(Isolate *isolate, double value)
static V8_WARN_UNUSED_RESULT Local< String > NewFromUtf8Literal(Isolate *isolate, const char(&literal)[N], NewStringType type=NewStringType::kNormal)
Definition: v8-primitive.h:415

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 -> { }
void Inherit(Local< FunctionTemplate > parent)

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.

Definition at line 467 of file v8-template.h.

Member Function Documentation

◆ Cast()

FunctionTemplate * Cast ( Data data)
static

Definition at line 1022 of file v8-template.h.

◆ GetFunction()

V8_WARN_UNUSED_RESULT MaybeLocal<Function> GetFunction ( Local< Context context)

Returns the unique function instance in the current execution context.

◆ HasInstance()

bool HasInstance ( Local< Value object)

Returns true if the given object is an instance of this function template.

◆ Inherit()

void Inherit ( Local< FunctionTemplate parent)

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.

◆ InstanceTemplate()

Local<ObjectTemplate> InstanceTemplate ( )

Get the InstanceTemplate.

◆ IsLeafTemplateForApiObject()

bool IsLeafTemplateForApiObject ( v8::Local< v8::Value value) const

Returns true if the given value is an API object that was constructed by an instance of this function template (without checking for inheriting function templates).

This is an experimental feature and may still change significantly.

◆ New()

static Local<FunctionTemplate> New ( Isolate isolate,
FunctionCallback  callback = nullptr,
Local< Value data = LocalValue >(),
Local< Signature signature = LocalSignature >(),
int  length = 0,
ConstructorBehavior  behavior = ConstructorBehavior::kAllow,
SideEffectType  side_effect_type = SideEffectType::kHasSideEffect,
const CFunction c_function = nullptr,
uint16_t  instance_type = 0,
uint16_t  allowed_receiver_instance_type_range_start = 0,
uint16_t  allowed_receiver_instance_type_range_end = 0 
)
static

Creates a function template.

◆ NewRemoteInstance()

V8_WARN_UNUSED_RESULT MaybeLocal<Object> NewRemoteInstance ( )

Similar to Context::NewRemoteContext, this creates an instance that isn't backed by an actual object.

The InstanceTemplate of this FunctionTemplate must have access checks with handlers installed.

◆ NewWithCache()

static Local<FunctionTemplate> NewWithCache ( Isolate isolate,
FunctionCallback  callback,
Local< Private cache_property,
Local< Value data = LocalValue >(),
Local< Signature signature = LocalSignature >(),
int  length = 0,
SideEffectType  side_effect_type = SideEffectType::kHasSideEffect 
)
static

Creates a function template backed/cached by a private property.

◆ NewWithCFunctionOverloads()

static Local<FunctionTemplate> NewWithCFunctionOverloads ( Isolate isolate,
FunctionCallback  callback = nullptr,
Local< Value data = LocalValue >(),
Local< Signature signature = LocalSignature >(),
int  length = 0,
ConstructorBehavior  behavior = ConstructorBehavior::kAllow,
SideEffectType  side_effect_type = SideEffectType::kHasSideEffect,
const MemorySpan< const CFunction > &  c_function_overloads = {} 
)
static

Creates a function template for multiple overloaded fast API calls.

References MemorySpan< T >::MemorySpan().

◆ PrototypeTemplate()

Local<ObjectTemplate> PrototypeTemplate ( )

A PrototypeTemplate is the template used to create the prototype object of the function created by this template.

◆ ReadOnlyPrototype()

void ReadOnlyPrototype ( )

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

◆ RemovePrototype()

void RemovePrototype ( )

Removes the prototype property from functions created from this FunctionTemplate.

◆ SetAcceptAnyReceiver()

void SetAcceptAnyReceiver ( bool  value)

When set to true, no access check will be performed on the receiver of a function call. Currently defaults to true, but this is subject to change.

◆ SetCallHandler()

void SetCallHandler ( FunctionCallback  callback,
Local< Value data = LocalValue >(),
SideEffectType  side_effect_type = SideEffectType::kHasSideEffect,
const MemorySpan< const CFunction > &  c_function_overloads = {} 
)

Set the call-handler callback for a FunctionTemplate. This callback is called whenever the function created from this FunctionTemplate is called. The 'c_function' represents a fast API call, see the comment above the class declaration.

References MemorySpan< T >::MemorySpan().

◆ SetClassName()

void SetClassName ( Local< String name)

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

◆ SetLength()

void SetLength ( int  length)

Set the predefined length property for the FunctionTemplate.

◆ SetPrototypeProviderTemplate()

void SetPrototypeProviderTemplate ( Local< FunctionTemplate prototype_provider)

A PrototypeProviderTemplate is another function template whose prototype property is used for this template. This is mutually exclusive with setting a prototype template indirectly by calling PrototypeTemplate() or using Inherit().

Friends And Related Function Documentation

◆ Context

friend class Context
friend

Definition at line 595 of file v8-template.h.

◆ ObjectTemplate

friend class ObjectTemplate
friend

Definition at line 596 of file v8-template.h.


The documentation for this class was generated from the following file: