Needstack - Texas Instruments TI-89 Developer's Manual

1108

NeedStack

Declaration: void NeedStack (short StackNeeded )
Category(ies): Utilities
Description: Throw an ER_MEMORY error if there is not at least StackNeeded bytes
available on the hardware stack. The hardware stack is 16K in size. When
a function calls another function the system will throw an ER_MEM_VIO
error if there is not enough hardware stack to make the call.
A function may have a complex set of operations that may not be easily
undone in a ONERR block. The function may also require that all of the
operations do not fail due to a lack of hardware stack. In this case, the
function can be started with a call to NeedStack to at least guarantee that
the hardware stack will not overflow during the critical section of the
function.
Inputs: StackNeeded — Minimum bytes of hardware stack required.
Outputs: May throw an ER_MEMORY error.
Assumptions: None
Side Effects: None
Availability: All versions of the TI-89 / TI-92 Plus.
TI-89 / TI-92 Plus
None
Differences:
See Also: None
Example: The cmd_copyvar function has a TRY/ENDTRY block in case some of the
operations it executes fail due to lack of heap memory (or because of
locked variables and the like). But since it also directly modifies elements of
the symbol table, it calls NeedStack first. The call to NeedStack insures
that none of the critical operations are partially completed due to a lack of
hardware stack thus leaving the symbol table in an undefined state. The
TI-BASIC interpreter uses the hardware stack to make recursive calls and
so all TI-BASIC commands and functions cannot rely on the hardware
stack being at any particular level.
NeedStack( 500 );
/* . . . prepare to do copy . . . */
TRY
/* . . . do copy . . . */
ONERR
/* . . . recover from any known error conditions . . . */
ENDTRY
TI-89 / TI-92 Plus Developer Guide
Appendix A: System Routines — Utilities
Not for Distribution Beta Version January 26, 2001