User-Level Native Thread Primitives (GThread) Library White Paper (G06.27+, H06.03+, J06.03+)

User-Level Native Thread Primitives (GThread Library) 02/15/2012
540065-004 Page 25 of 44
Return: int16
Returns zero if restore completed successfully. nonzero indicates the restore failed due to a static
thread model or an invalidated or discontiguous swap area.
Considerations:
The routine does not validate that the thread control block supplied belongs to the currently
executing thread. If the control block of a suspended thread is provided, corruption of the specified
thread’s runtime environment occurs. This interface has the same requirements as the original
approach where the client performed the restoration function manually – the interface must be called
within the target routine specified in a call to GTHREAD_SWAPIN_SETUP_.
2.11. Measuring and Checking Stack Usage
A simple method clients can use to analyze the stack usage of an unprotected thread is to allocate an
oversized memory space for the stack and fill that space with a fixed pattern. The thread is then allowed
to run (with emphasis on testing all possible code paths) and prior to terminating the thread, the memory
space is examined. Stack usage is determined by walking the memory space to locate the point at which
the fixed pattern has been overwritten. This determination requires the client to understand the mechanics
of stack growth:
• For TNS platforms, the stack grows from low to high addresses
• For non TNS/E native platforms, the stack grows from high to low addresses
• For TNS/E native platforms, there are two stacks growing in opposite directions
The GThreads library provides the GTH_THREAD_USAGE_ and GTH_VALIDATE_GUARD_
functions to aid the client in determining stack usage without having to understand platform specifics.
Additionally, the Swaptions argument to GTHREAD_INITIATE_ allows the client to specify that a fixed
pattern should be written into the memory allocated for the unprotected static stack. A Swaptions bit,
GTS_STATIC_FILL is created for this purpose. The bit can be logically ORed with any other
GTS_STATIC_xxx define. (If both GTS_STATIC_FILL and GTS_SWAPPED occur in the same call,
GTHREAD_INITIATE_ reports GT_BAD_SWAPTIONS.) A call to GTHREAD_INITIATE_ utilizing
the new option is as follows:
GTHREAD_INITIATE_(...,
length,
(GTS_STATIC_FILL | GTS_STATIC_RegPerCent(30)),
...);
2.11.1. Thread Stack Usage
GTH_THREAD_USAGE_( GThread_CB cb, int32* mem_alloc, int32* mem_used, int32* reg_alloc,
int32* reg_used )
Description:
This function returns information about the allocated size of the stack. For an unprotected static stack
it can also return information about the amount of memory used, providing the thread was created by
GTHREAD_INITIATE_ with the GTS_STATIC_FILL value in the Swaptions parameter. It is not
usable for the Main thread.