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 30 of 46
2.12. Context Manipulation
GTHREAD_SETJMP_( GThread_CB cb, GTH_FUNC SuspendProc )
Description:
An augmented implementation of the C setjmp() function. Callable 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