====================
Value stack resizing
====================

Growing and shrinking the value stack is important for both performance and
memory usage.  This document describes the mechanism in Duktape 2.2.

Value stack concepts
====================

The value stack is a single ``duk_tval`` array which is used by all calls in
the call stack of a certain Duktape thread.  The value stack has:

* An allocated size.  This is the actual memory allocation.

* A reserved size.  This is the value stack size that application or Duktape
  code has reserved.  The value stack cannot be shrunk below this size even in
  an emergency GC because calling code is expecting the reserved size to be
  guaranteed in all situations.

  - The current thread-level reserved size is the maximum reserved size for
    all activations in the call stack.  Call handling deals with updating the
    thread level reserve as calls are wound and unwound.

  - The reserve can only grow when calling functions because it would
    otherwise be unsafe to unwind protected calls as the unwind might run out
    memory.  That's a problem because either the unwind path would throw, or
    fail to respect the value stack guarantees for the reserve.  Both are
    sandboxing issues.  This strict policy technically only needs to be applied
    to protected calls, but it is applied to all calls at present.

  - The current reserve is also valid and tracked when the call stack is
    empty.  The reserve is then valid for the C code operating on the empty
    call stack.

* Current "top" of the value stack.  Value stack entries above top are not
  currently in use, and are always set to Ecmascript ``undefined`` as part
  of the value stack initialization policy.

  - Calling code is allowed to push values at the "top" index up to the
    current reserve.

  - It's not allowed to push values beyond the reserve, even if there is
    space between the reserve and the current allocation.  By default such
    pushes will throw; with ``DUK_USE_VALSTACK_UNSAFE`` (Lua-like behavior)
    such pushes will cause undefined behavior.

* Current "bottom" of the value stack.  This provides the basis for API call
  index resolution: index 0 is at the bottom.

  - When a call is in progress, "bottom" matches the functions' conceptual
    value stack frame.

  - When no call is in progress, "bottom" is zero.

Whenever side effects or value stack operations are possible, these values
must fulfill::

    0 <= bottom <= top <= reserve <= allocated