How to work with lightfuncs

Lightfunc overview

When a normal native function is created using duk_push_c_function() two heap allocations are needed:

In very low memory environments the memory cost of this representation adds up when multiplied for e.g. 100 functions.

The lightfunc type provides a very lightweight alternative to representing function objects. A lightfunc represents a native function using just a tagged value (duk_tval) with no heap allocations, thus taking no more space than representing e.g. a boolean value. In concrete terms:

Because there are no heap allocations related to lightfuncs, there are some limitations, with the most important being:

Example of a lightfunc name:

duk> Math.cos.name
= "light_08067ce4_0511"

The name is autogenerated and includes the native function pointer (here 08067ce4) and the 16-bit flags field (here 0x0511).

See also: http://duktape.org/guide.html#type-lightfunc.

Creating lightfuncs

Lightfuncs can only be created from C code as:

/* http://duktape.org/api.html#duk_push_c_lightfunc */

duk_push_c_lightfunc(ctx, my_adder, 2 /*nargs*/, 2 /*length*/, 0 /*magic*/);

Usually nargs and length fields will have the same value. The magic field can be ignored and set to zero if the native function doesn't need it.

Making built-in functions lightfuncs

The ECMAScript built-in functions Math.cos, Array.prototype.join, etc are all by default ordinary Function objects and consume a significant amount of memory (more than 20kB on a 32-bit low memory target).

To save memory, you can enable the following option:

When enabled, built-in functions will be converted to lightfuncs during their initialization. A few built-in functions cannot be safely converted to lightfuncs; they will remain normal Functions.

The downside of this option is that the converted built-ins will have a less useful .name, for example.