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 7 of 44
2. Thread Primitives
The primitives defined below constitute a facility called "GThread." Procedure and structure identifiers
begin with "GTHREAD" or “GTH” (for "Guardian Thread"), in contrast with the "pthread" identifiers
specified for POSIX threads, and to avoid conflict with identifiers in existing thread packages. Defines
and literals begin "GT".
These facilities are regarded as primitives in two senses: they perform low-level functions, and they
typically are hidden from the client application by a higher-level thread package. The "application" and
the "thread package" (if any) are collectively called the "program" in this document.
The GThread Primitives support user-level threads for unprivileged processes using either the master or
peer protocol and either static or swapped stacks (or a mixture of both). For multithreading purposes, a
process is unprivileged if its code is unprivileged whenever one of the thread primitives is called.
2.1. Thread Context
Multithreading requires the following operations on process context:
• Saving the context when suspending a thread,
• Restoring the context when resuming a thread,
• Creating the initial context of a new thread.
For static threads, this context is just the contents of certain processor registers. For swapped threads, the
context also includes the procedure activation records (stack frames) for procedures currently active in the
thread. GThread primitives maintain the register context and provide the address ranges of the stack
frames, and they provide a function to copy the stack data.
Thread register context is maintained in "jump buffers," the data structures used by the standard C
setjmp() and longjmp() functions. The jump buffer is augmented with other needed thread data.
2.2. Declarations
Declarations and statements must occur in the program to set up and initialize the GThread facilities. The
primitives are exported to the program as declaration files including structures, literals, defines, and
external procedures. For pTAL and EpTAL programs, the header file HGTHREAD must be sourced in. A
program in C or C++ must include the header file GTHREADH (gthread.h) instead. The same header file
serves both TNS and native TNS/R or TNS/E programs; the appropriate text is selected at compile time
on the basis of the target architecture.
2.3. Thread Structures
The basic control structure for a thread is a control block called a GThread_CB. Each thread is identified
to the primitive routines by a reference to its GThread_CB; this address is used as a handle. A thread
package may expose this handle to its clients, or may use some other identification (such as an index into
an array of GThread_CB pointers). For compactness, the following structure definitions and parameter
specifications use "GThreadCB" as a type, whereas TAL, pTAL, and EpTAL actually need structure
pointers (see GTHREAD_CB define).