Concepts

Heap

A single region for garbage collection. Shared by one or more contexts.

Context

A handle used in the Duktape API, associated with a Duktape thread (coroutine) and its call and value stacks.

Call stack (of a context)

Book-keeping of the active function call chain of a context. Includes both ECMAScript and Duktape/C function calls.

Value stack (of a context)

Storage for tagged values belonging to current activations in a context's call stack.

The values kept in a value stack are traditional tagged types. Stack entries are indexed either from the bottom (>= 0) or from the top (< 0) of the most recent function call.

Value stack index

Non-negative (>= 0) indices refer to stack entries in the current stack frame, relative to the frame bottom:

[ 0 1 2 3 4 5! ]

Negative (< 0) indices refer to stack entries relative to the top:

[ -6 -5 -4 -3 -2 -1! ]

The special constant DUK_INVALID_INDEX is a negative integer which denotes an invalid stack index. It can be returned from API calls and can also be given to some API calls to indicate a "no value".

The value stack top (or just "top") is the non-negative index of an imaginary element just above the highest used index. For instance, above the highest used index is 5, so the stack top is 6. The top indicates the current stack size, and is also the index of the next element pushed to the stack.

[ 0 1 2 3 4 5! 6? ]

Stack type

The "Heap alloc" column indicates whether the tagged value points to a heap allocated object with possibly additional allocations (like object property table).

Stack type mask

Each stack type has a bit index which allows a set of stack types to be represented as a bit mask. Calling code can use such bit sets to e.g. check whether or not a certain stack value belongs to a set of types. Example:

if (duk_get_type_mask(ctx, -3) & (DUK_TYPE_MASK_NUMBER |
                                  DUK_TYPE_MASK_STRING |
                                  DUK_TYPE_MASK_OBJECT)) {
    printf("type is number, string, or object\n");
}

There is a specific API call for matching a set of types even more conveniently:

if (duk_check_type_mask(ctx, -3, DUK_TYPE_MASK_NUMBER |
                                 DUK_TYPE_MASK_STRING |
                                 DUK_TYPE_MASK_OBJECT)) {
    printf("type is number, string, or object\n");
}

Array index

ECMAScript object and array keys can only be strings; this includes array indices (0, 1, 2, ...) which are expressed as canonical string representations ("0", "1", "2", ...) of the respective numbers for all integers in the range [0, 2**32-2]. Conceptually any key used in a property lookup is first coerced to a string, so that obj[123] is really just a shorthand for obj["123"].

Duktape tries to avoid explicit number-to-string conversions for array accesses whenever possible, so it is preferable to use numeric array indices in both ECMAScript code and C code using the Duktape API. There are typically API call variants accepting strings and numeric indices.

Duktape/C function

A C function with a Duktape/C API signature can be associated with an ECMAScript function object or a lightfunc value, and gets called when the associated value is called from ECMAScript code. Example:

duk_ret_t my_func(duk_context *ctx) {
    duk_push_int(ctx, 123);
    return 1;
}

Argument count given in value stack is specified when the corresponding ECMAScript function object is created: either a fixed number of arguments of DUK_VARARGS for getting arguments "as is":

• When using a fixed number of arguments, extra arguments are dropped and missing arguments padded with undefined as necessary.
• When using DUK_VARARGS, use duk_get_top() to determine the number of actual arguments.

Function return values:

• Return value 1: stack top contains return value.
• Return value 0: return value is undefined.
• Return value <0: shorthand for throwing errors, use DUK_RET_xxx constants which are negative variants of DUK_ERR_xxx.
• Return value >1: reserved, currently invalid.

No error message can be given when using the error shorthand:

duk_ret_t my_func(duk_context *ctx) {
    if (duk_get_top(ctx) == 0) {
        /* throw TypeError if no arguments given */
        return DUK_RET_TYPE_ERROR;
    }
    /* ... */
}

Stashes

A stash is an object reachable from C code using the Duktape/C API, but which is unreachable from ECMAScript code. Stashes allow C code to store internal state which can be safely isolated from ECMAScript code. There are three stashes:

• Heap stash: shared by all threads in the same heap.
• Global stash: shared by all threads which share a global object.
• Thread stash: specific to a certain thread.