Ensure that the value stack has at least extra reserved (allocated) elements for caller's use. Returns 1 if successful, 0 otherwise. If the call is successful, the caller is guaranteed that extra elements can be pushed to the value stack without a value stack related error (other errors like out-of-memory can still occur). The caller MUST NOT rely on being able to push more than extra values; although this is possible, such elements are reserved for Duktape's internal use.
Upon entry to a Duktape/C function and when outside any call there is an automatic reserve (of XXX elements) allocated for the caller. If more value stack space is needed, the caller must reserve more space explicitly either in the beginning of the function (e.g. if the number of elements required is known or can be computed based on arguments) or dynamically (e.g. inside a loop). Note that an attempt to push a value beyond the currently allocated value stack causes an error: it does not cause the value stack to be automatically extended. This simplifies the internal implementation.
In addition to user reserved elements, Duktape keeps an automatic internal value stack reserve to ensure all API calls have enough value stack space to work without further allocations. The value stack is also extended in somewhat large steps to minimize memory reallocation activity. As a result the internal number of value stack elements available beyond the caller specified extra varies considerably. The caller does not need to take this into account and should never rely on any additional elements being available.
As a general rule duk_require_stack() should be used instead of this function to reserve more stack space. If value stack cannot be extended, there is almost never a useful recovery strategy except to throw an error and unwind.
=example int nargs; nargs = duk_get_top(ctx); /* number or arguments */ /* reserve space for one temporary for each input argument */ if (!duk_check_stack(ctx, nargs * 2)) { /* return 'undefined' if cannot allocate space */ printf("failed to reserve enough stack space\n"); return 0; } /* ... */ =tags stack =seealso duk_require_stack =fixme The automatic user reserve must be exposed by duktape.h and the current value should be indicated here.