How to allocate and de-allocate cleanup stacks

This document describes when and how a cleanup stack should be allocated and de-allocated.

The main categories of programs (GUI applications and servers) both have cleanup stacks created for them as part of their respective frameworks. Simple console programs for test and demonstration purposes though require a cleanup stack to be explicitly allocated.

Allocate the stack at the beginning of the thread as follows:

TheTrapCleanup=CTrapCleanup::New();

De-allocate the cleanup stack at the end of the thread as follows:

delete TheTrapCleanup;

Notes

This explicit allocation and de-allocation is necessary for threads which use cleanup processing. Threads which do not use cleanup stack processing need not allocate a cleanup stack.
Note that the cleanup stack variable name (TheTrapCleanup in this case) is only used to reference the stack when it needs to be destroyed. Therefore the user is at liberty to give the stack any valid variable name. Multiple cleanup stacks are supported: the system holds a stack of cleanup stacks, of which the top item is the current cleanup stack. As such, when a new stack is created it is pushed onto the stack of cleanup stacks, making it the current cleanup stack. When it is destroyed, it is pushed off the stack of cleanup stacks making the previously stacked cleanup stack the current one.