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