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 19 of 44
reg_used – Pointer to location for the amount of reg stack space being used in bytes at the
point where GTHREAD_SETJMP_ was last called.
Return: none
Considerations:
This interface returns stack usage information captured at the last call to GTHREAD_SETJMP_
when the thread was active. It is provided for users of swapped threads who wish to manage swap-
area overflow or overflow of the unthreaded (master) code. This interface should not be used to
monitor stack usage on a running thread; its result is valid only after a call to GTHREAD_SETJMP_.
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 these
cases, the reg_used argument has no meaning and defaults to returning zero if passed when calling
GTH_STACK_USED_DETAIL_.
GTH_SET_ALLOCATION_( GThread_CB cb, void * saveArea, int32 size )
Description:
Permits a client to change the swap area. This is primarily used as part of swap area overflow
avoidance in swapped stack threading implementations. May be called only for a swapped thread.
Replaces accessing (modifying) the thread control block elements SwapArea and StackSize,
Input:
cb - The address of the thread control block being modified
saveArea - A pointer to the new save area
size - The size of the new save area in bytes.
Return: int16
Returns zero if change completed successfully. nonzero indicates the change failed because the
interface tried to adjust the swap area of a static thread.
Considerations:
The caller is responsible for disposing of the current swap area, typically before calling this routine.
This call must occur when the contents of the current swap area are no longer needed. Typically, for
handling swap area overflows, this routine is called as part of saving a suspending thread’s stack
after calls to GTHREAD_SETJMP_ and GTH_STACK_USED_. Refer to Section 2.4 for buffer
alignment considerations.
GTH_STACK_CHECK_ACTIVE_( GThread_CB cb, int32 stack_delta )
Description:
Permits a client to determine whether there is a specified amount of stack space available on an
active static thread using the current stack pointers. May be called only for an unprotected static
thread. This replaces accessing the thread control block elements StackSize, StackOrigin, and then
performing a check against the current value of the stack pointer (sp).
Input:
cb - The address of the currently active thread control block.