The Getting started: line processing example illustrated how C code can call into ECMAScript to do things that are easy in ECMAScript but difficult in C.
The example in this article illustrates the reverse, how ECMAScript code can call C code: while scripting is useful for many things, it is not optimal for low level byte or character processing. Being able to call optimized C helpers allows you to write most of your script logic in nice ECMAScript but call into C for the performance critical parts. Another reason for using native functions is to provide access to native libraries.
To implement a native function you write an ordinary C function which conforms to a special calling convention, the Duktape/C binding. Duktape/C functions take a single argument, a Duktape context, and return a single value indicating either error or number of return values. The function accesses call arguments and provides return values through the Duktape context's value stack, manipulated with the Duktape API. We'll go deeper into Duktape/C binding and the Duktape API later on.
Here's a simple example:
duk_ret_t my_native_func(duk_context *ctx) {
double arg = duk_require_number(ctx, 0 /*index*/);
duk_push_number(ctx, arg * arg);
return 1;
}Let's look at this line by line:
double arg = duk_require_number(ctx, 0 /*index*/);Check that the number at value stack index 0 (bottom of the stack, first
argument to function call) is a number; if not, throws an error and never
returns. If the value is a number, returns it as a double.
duk_push_number(ctx, arg * arg);Compute square of argument and push it to the value stack.
return 1;Return from the function call, indicating that there is a (single) return
value on top of the value stack. Multiple return values are not yet supported.
You could also return 0 to indicate that no return value is given in which
case Duktape defaults to ECMAScript undefined.
A negative return value causes an error to be automatically thrown: this is
a shorthand for throwing errors conveniently. Note that you don't need to
pop any values off the stack yourself, Duktape will do that for you
automatically when the function returns. See
Programming model for more
details.
We'll use a primality test as an example for using native code to speed up ECMAScript algorithms. More specifically, our test program searches for primes under 1000000 which end with the digits '9999'. The ECMAScript version of the program is:
Note that the program uses the native helper if it's available but falls back to an ECMAScript version if it's not. This allows the ECMAScript code to be used in other containing programs. Also, if the prime check program is ported to another platform where the native version does not compile without changes, the program remains functional (though slower) until the helper is ported. In this case the native helper detection happens when the script is loaded. You can also detect it when the code is actually called which is more flexible.
A native helper with functionality equivalent to primeCheckECMAScript()
is quite straightforward to implement. Adding a program main and a simple
print() binding into the ECMAScript global object, we get primecheck.c:
The new calls compared to Getting started: line processing are, line by line:
int val = duk_require_int(ctx, 0);
int lim = duk_require_int(ctx, 1);These two calls check the two argument values given to the native helper.
If the values are not of the ECMAScript number type, an error is thrown.
If they are numbers, their value is converted to an integer and assigned to
the val and lim locals. The index 0 refers to the first function
argument and index 1 to the second.
Technically duk_require_int() returns a duk_int_t; this
indirect type is always mapped to an int except on rare platforms where
an int is only 16 bits wide. In ordinary application code you don't
need to worry about this, see
C types for more discussion.
duk_push_false(ctx);
return 1;Pushes an ECMAScript false to the value stack. The C return value 1
indicates that the false value is returned to the ECMAScript caller.
duk_push_global_object(ctx);
duk_push_c_function(ctx, native_prime_check, 2 /*nargs*/);
duk_put_prop_string(ctx, -2, "primeCheckNative");The first call, like before, pushes the ECMAScript global object to the
value stack. The second call creates an ECMAScript Function object
and pushes it to the value stack. The function object is bound to the
Duktape/C function native_prime_check(): when the ECMAScript function
created here is called from ECMAScript, the C function gets invoked.
The second call argument (2) indicates how many arguments the C
function gets on the value stack. If the caller gives fewer arguments,
the missing arguments are padded with undefined; if the caller gives
more arguments, the extra arguments are dropped automatically. Finally, the
third call registers the function object into the global object with the
name primeCheckNative and pops the function value off the stack.
duk_get_prop_string(ctx, -1, "primeTest");
if (duk_pcall(ctx, 0) != 0) {
printf("Error: %s\n", duk_safe_to_string(ctx, -1));
}
duk_pop(ctx); /* ignore result */When we come here the value stack already contains the global object
at the stack top. Line 1 looks up the primeTest function from the
global object (which was defined by the loaded script). Lines
2-4 call the primeTest function with zero arguments, and prints out an
error safely if one occurs. Line 5 pops the call result off the stack;
we don't need the return value here.
Compile as before:
# src/ contains Duktape sources from the distributable or prepared
# explicitly using tools/configure.py.
$ gcc -std=c99 -o primecheck -Isrc/ src/duktape.c primecheck.c -lm
Test run, ensure that prime.js is in the current directory:
$ time ./primecheck
Have native helper: true
49999 59999 79999 139999 179999 199999 239999 289999 329999 379999 389999
409999 419999 529999 599999 619999 659999 679999 769999 799999 839999 989999
real 0m2.985s
user 0m2.976s
sys 0m0.000s
Because most execution time is spent in the prime check, the speed-up
compared to plain ECMAScript is significant. You can check this by editing
prime.js and disabling the use of the native helper:
// Select available helper at load time
var primeCheckHelper = primeCheckECMAScript;
Re-compile and re-run the test:
$ time ./primecheck
Have native helper: false
49999 59999 79999 139999 179999 199999 239999 289999 329999 379999 389999
409999 419999 529999 599999 619999 659999 679999 769999 799999 839999 989999
real 0m23.609s
user 0m23.573s
sys 0m0.000s