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 8 of 44
The program must provide a GThread_CB and a stack or swap area for each thread it creates. A thread
package can include a GThread_CB as a substruct or overlay of a larger structure associated with its own
thread implementation. For simplicity, especially in diagnostic situations, the GThread_CB fields should
occur at the front of the structure.
The program must provide a GThread_CB for the original thread of the process. In this document, this
object is called "MainCB," which is the name of the formal parameter which is passed in several GThread
procedures. The program must retain the MainCB as global state; for native threads its location is
recorded in process state for possible diagnostic use. In a swapping model using peer protocol, the
program must also supply a stack swap area for the main thread.
The program should typically maintain a global pointer to the current GThread_CB. Within this
document, this pointer is called "CurThread".
Some of the GThread_CB contents are private to GThread; others are shared with the program. On
TNS/R platforms, all the elements shown below are accessible to clients. On TNS/E platforms, only
LinkNext, LinkPrev, and GTh_Marker are accessible to clients. Several fields are also available to the
NonStop operating system for diagnostic purposes.
The "GThread_CB" structure contains the following:
GThreadCB LinkNext, LinkPrev: are reserved for the program for linking the thread onto lists (or
any other purpose). These fields are not used by the GThread primitives. When compiled with LP64
data model, the fields are 64-bit pointers; otherwise they remain 32-bit pointers with 32-bit fillers.
• INT(32) GTh_Marker is an eye-catcher and version field. It is set to the value of the
GTHREAD_VERSION literal by the GTHREAD_INITIATE_ procedure, and destroyed by the
GTHREAD_TERMINATE_ procedure.
• GThreadCB ThreadNext, ThreadPrev are links to the next (younger) and previous (older) thread
currently defined in this process. These fields in MainCB anchor a doubly linked list.
GTHREAD_INITIATE_ and GTHREAD_TERMINATE_ link and de-link new and defunct threads;
the GTHREAD_INITIALIZE_ procedure initializes the anchors. The list is available to the NonStop
operating system for diagnostic use.
For TNS or TNS/R threads, many of the following members relate to the single stack. For TNS/E, which
must deal with two stack components, they are private; equivalent information can be acquired via the
interfaces described in Section 2.9.
• STRING .EXT StackOrigin designates the stack origin for the thread; it is set by the
GTHREAD_INITIATE_ procedure and used by the GTHREAD_SETJMP_ procedure. For static
threads, StackOrigin designates the program-allocated stack area. For swapped threads, it is the "swap
origin," the demarcation between the stack root and the swapped part of the process stack. The
GTHREAD_ORIGIN_SET_ or GTHREAD_ORIGIN_SET_MOD_ procedures set the current tip of
the Main stack into MainCB.StackOrigin, which GTHREAD_INITIATE_ copies into the CB of other
swapped threads.
• INT(32) StackSize is the stack size allocated for the thread. This field is set by
GTHREAD_INITIATE_. It is available for limit checking.
• STRING .EXT SwapArea specifies the swap area. It is set by GTHREAD_INITIATE_ and used by
the GThread primitives, which manage swapped stacks. It is available to the NonStop operating
system for possible diagnostic use. The field contains zero for a static thread, or the starting address
of a contiguous swap area, or an invalid value for a swapped thread whose swap area is discontiguous
(TNS / TNS/R only) or invalidated. See SwapArea defines.