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 26 of 44
Input:
cb - The address of the thread control block for the thread being analyzed.
mem_alloc_ – Pointer to location for the size in bytes of the space allocated for the mem stack.
mem_used – Pointer to location for the size in bytes of the mem stack area used by the thread
while running.
reg_alloc – Pointer to location for the size in bytes of the space allocated for the reg stack.
On platforms other than TNS/E native, zero is returned.
reg_used – Pointer to location for the size in bytes of the reg stack area used by the thread
while running.
On platforms other than TNS/E native, zero is returned.
Return: none
Considerations:
For this function to report valid usage information, the following is required:
1) The GTS_STATIC_FILL Swaption must have been specified during GTHREAD_INITIATE_
for an unprotected thread stack. 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 primarily as a tool for analyzing stack usage for unprotected stacks. 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.
Use of this function with protected stacks is deprecated. For protected stacks on TNS/E systems it
sets mem_used and reg_used to –1; it sets mem_alloc_ and reg_alloc to the current size of the
memory and register stack areas, retrieved from the operating system. These sizes can increase
during the life of the stack, if it was originally allocated with room for growth, and growth has
occurred; see § 3.6.2.2.
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 for unprotected static stacks: