duktape/website/api/duk_check_stack.txt

=proto
int duk_check_stack(duk_context *ctx, unsigned int extra);

=summary
<p>Ensure that the value stack has at least <code>extra</code> reserved
(allocated) elements for caller's use.  Returns 1 if successful, 0
otherwise.  If the call is successful, the caller is guaranteed that
<code>extra</code> 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
<code>extra</code> values; although this is possible, such elements are
reserved for Duktape's internal use.</p>

<!--FIXME-->
<p>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.</p>

<p>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 <code>extra</code> varies considerably.
The caller does not need to take this into account and should never
rely on any additional elements being available.</p>

<p>As a general rule
<code><a href="#duk_require_stack">duk_require_stack()</a></code> 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.</p>

=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.