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 28 of 44
2.12. Context Manipulation
GTHREAD_SETJMP_( GThread_CB cb, GTH_FUNC SuspendProc )
Description:
An augmented implementation of the C setjmp() function. May be called for either static or swapped
threads.
Input:
cb – The address of a thread control block that will receive the current context. On
TNS/E, this must be aligned on a 16-byte boundary.
SuspendProc - is GTH_NULL_PROCADDR or designates a procedure with one parameter, the CB
of the current thread.
Return: int32
See Considerations for this function.
Considerations:
GTHREAD_SETJMP_ saves the current register context into the designated GThread_CB,
determines the current stack usage, and (if SuspendProc is null) returns 0d.
A subsequent invocation of GTHREAD_LONGJMP_ with the same CB causes the process to return
again to the GTHREAD_SETJMP_ call site, with a nonzero function value.
If the SuspendProc procedure is not GTH_NULL_PROCADDR, the designated procedure is called
and passed the CB, after the current context is placed into it. A SuspendProc typically calls
GTHREAD_LONGJMP_ to resume another thread, in which case the only return from the
GTHREAD_SETJMP_ call will be the one with a nonzero result caused by a subsequent
GTHREAD_LONGJMP_ call with this CB. (If for some reason the SuspendProc does return, it must
be an int32 function returning 0d.)
Entering the suspend procedure from GTHREAD_SETJMP_ reduces the amount of stack space in
use for the suspended thread, compared with having the suspend procedure call
GTHREAD_SETJMP_. While this optimization is significant only for swapped threads, the same
program structure can be used with static threads as well.
GTHREAD_SETJMP_ generates a SIGFPE signal (Arithmetic Overflow trap) on TNS/R or a
SIGILL signal (Instruction Failure) on TNS/E, if CB.GTh_Marker is not GTHREAD_VERSION.
On TNS/E, GTHREAD_SETJMP_ also generates a SIGILL signal if the GThread control block isn’t
aligned on a 16-byte boundary.
NOTE: When a procedure is reentered at a setjmp call site, it is indeterminate whether the values of
non-VOLATILE local variables have their values from setjmp or longjmp time. This issue does not
arise when GTHREAD_SETJMP_ and GTHREAD_LONGJMP_ are used only to switch threads