duktape/website/api/duk_safe_call.txt

=proto
duk_int_t duk_safe_call(duk_context *ctx, duk_safe_call_function func, duk_idx_t nargs, duk_idx_t nrets);

=stack
[ ... arg1! ...! argN! ] -> [ ... ret1! ...! retN! ]

=summary
<p>Perform a protected pure C function call inside the current value stack frame
(the call is not visible on the call stack).  <code>nargs</code> topmost values in the
current value stack frame are identified as call arguments, and <code>nrets</code>
return values are provided after the call returns.</p>

<p>The return value is:</p>
<ul>
<li><code>DUK_EXEC_SUCCESS</code> (0): call succeeded, <code>nargs</code> arguments are replaced
    with <code>nrets</code> return values.  (This return code constant is guaranteed to be
    zero, so that one can check for success with a "zero or non-zero" check.)</li>
<li><code>DUK_EXEC_ERROR</code>: call failed, <code>nargs</code> arguments are replaced with
    <code>nrets</code> values, first of which is an error value and the rest are <code>undefined</code>.
    (In exceptional cases, e.g. when there are too few arguments on the value stack, the call
    returns non-zero but may leave the stack in an inconsistent state.)</li>
</ul>

<div class="note">
Unlike most Duktape API calls, this call returns zero on success.  This allows
multiple error codes to be defined later.
</div>

<p>Because this call operates on the current value stack frame, stack behavior
differs a bit from other call types.  Although the target function signature
matches Duktape/C functions, value stack and return code policies are different.</p>

<p>The top <code>nargs</code> elements of the stack top are identified as arguments to
<code>func</code> establishing a "base index" for the return stack as:</p>
<pre>
(duk_get_top() - nargs)
</pre>

<p>When <code>func</code> returns, it indicates with its return value the number of
return values it has pushed on top of the stack; multiple or zero return
values possible.  The stack is then manipulated so that there are exactly
<code>nrets</code> values starting at the "base index" established before the call.</p>

<p>Note that since <code>func</code> has full access to the value stack, it may modify
the stack below the indended arguments and even pop elements below the "base index"
off the stack.  Such elements are restored with <code>undefined</code> values before
returning, to ensure that the stack is always in a consistent state upon returning.</p>

<p>If an error occurs, the stack will still have <code>nrets</code> values at "base index";
the first of such values is the error, and the remaining values are <code>undefined</code>.
If <code>nrets</code> is zero, the error will not be present on the stack (the return stack
top will equal the "base index"), so calling this function with <code>nrets</code> as 0
is not very useful.</p>

<p>Example with <code>nargs = 3</code>, <code>nrets = 2</code>, <code>func</code> returns 4.
Pipe chars indicate logical boundaries:</p>

<pre>
      .--- frame bottom
      |
      |     .--- "base index"
      v     v
[ ... | ... | a b c ]            stack before calling 'func'

[ ... | ... | a b | x y z w ]    stack after calling 'func', which has
                                 popped one argument and written four
                                 return values (and returned 4)

[ ... | ... | x y ]              stack after duk_safe_call() returns,
                                 2 (= nrets) first 'func' return values
                                 are left at "base index"
</pre>

<div class="note">
Note that <code>func</code> uses caller stack frame, so bottom-based references
are dangerous within 'func'.
</div>

=example
duk_ret_t my_func(duk_context *ctx) {
    double a, b, c;

    a = duk_get_number(ctx, -3);
    b = duk_get_number(ctx, -2);
    c = duk_get_number(ctx, -1);  /* ignored on purpose */
    duk_push_number(ctx, a + b);

    /* Indicates that there is only one return value.  Because the caller
     * requested two (nrets == 2), Duktape will automatically add an
     * additional "undefined" result value.
     */
    return 1;
}

duk_int_t rc;

duk_push_int(ctx, 10);
duk_push_int(ctx, 11);
duk_push_int(ctx, 12);
rc = duk_safe_call(ctx, my_func, 3 /*nargs*/, 2 /*nrets*/);
if (rc == DUK_EXEC_SUCCESS) {
    printf("1st return value: %s\n", duk_to_string(ctx, -2));  /* 21 */
    printf("2nd return value: %s\n", duk_to_string(ctx, -1));  /* undefined */
} else {
    printf("error value: %s\n", duk_to_string(ctx, -2));
}
duk_pop_2(ctx);

=tags
call
protected