User-Level Native Thread Primitives (GThread) Library White Paper (G06.26+)

User-Level Native Thread Primitives (GThread Library) 03/31/2005
Hewlett-Packard Company--540065-001 Page 28 of 46
mem_used – Pointer to location for the size of the mem stack, in bytes, used by the thread
while running.
reg_alloc – Pointer to location for the size of the allocated space, in bytes, reserved for the
reg stack.
On platforms other than TNS/E native, zero is returned.
reg_used – Pointer to location for the size of the reg stack, in bytes, used by the thread while
running.
On platforms other than TNS/E native, zero is returned.
Return: none
Considerations:
For this function to work properly, the following is required:
1) The GTS_STATIC_FILL Swaption must have been specified during GTHREAD_INITIATE_
for the specified thread. See Section 2.11 for more information on this option.
2) The thread must either be running or have been run prior to calling GTH_THREAD_USAGE_.
All output parameters are optional, in the sense that if the caller passes a NULL pointer, the
associated value is not reported.
On platforms other than TNS/E native, the concept of a separate reg stack does not exist. In that
instance the reg_alloc and reg_used arguments have no meaning and default to returning zero if
passed when calling GTH_THREAD_USAGE_.
This function is provided as a tool for analyzing stack usage. It performs the analysis by walking the
allocated space to locate the point where the fixed pattern set during GTHREAD_INITIATE_ has
been overwritten. While this process is as efficient as possible, clients are advised to use this routine
for design and sizing analysis only and avoid calling this routine frequently in normal production
environments.
2.11.2. Stack ‘Guard Area’ Protection
One of the methods described in Section 3.6.3.2 for detecting that the stack has overflowed for a given
thread is to allocate additional space during GTHREAD_INITIATE_ for ‘guard areas’ which could be
filled with a fixed data pattern and validated prior to switching thread contexts.
Coupled with specifying GTS_STATIC_FILL in the GTHREAD_INITIATE_ call, the following
interface provides a built in mechanism for performing guard area validation:
GTH_VALIDATE_GUARD_( GThread_CB cb, int32 mem_guard, int32 reg_guard )
Description:
Performs a validation of the pattern written during GTHREAD_INITIATE_ in the allocated stack
area. The validation is performed starting at the ‘end of the stack area’ allocated for the specified
length. The ‘end of the stack area’ is defined as the end of the allocated area based on the direction
of stack growth. On TNS/E platforms, the stack areas allocated for both the mem and reg stacks are
checked.