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 16 of 46
Return: int16
Returns zero if the function succeeds. Returns GT_BAD_MAIN_CB, GT_BAD_CB_NEXT,
GT_BAD_CB_PREV, GT_BAD_..._ALIGN (four cases), GT_BAD_ARGLEN,
GT_BAD_LENGTH, or GT_BAD_SWAPTIONS if an error is detected.
Considerations:
The ArgStart parameter described above designates a set of discrete argument values, not a string
being passed as a single argument. The value string is copied to the new thread by
GTHREAD_INITIATE_, so ArgStart can designate a local area. Any actual argument value can be
a pointer. However, any object designated by a pointer must have a stable lifetime and address,
remaining accessible to the new thread when it becomes active. It must not designate something
local to procedure (such as the one that invokes GTHREAD_INITIATE_) that will exit
immediately. In the swapping models, it must not designate anything local to any thread.
To avoid architecture dependencies in parameter passing, the initial procedure should have a simple
calling sequence (not EXTENSIBLE or VARIABLE) with a fixed number of 32-bit parameters,
such as INT(32) values or INT/STRING .EXT pointers. (In native C/C++, or TNS C with the wide
model, parameters should be int or pointer values.) Thus ArgStart designates an array of N 32-bit
values, and ArgLen is 4*N. (Without these restrictions, the program must account for architecture-
dependent alignment and width requirements for passing 16- or 64-bit arguments, and must provide
any VARIABLE/EXTENSIBLE mask/count words, which differ in format and placement between
TNS, TNS/R, and TNS/E calls.) On TNS/E platforms, the GThread implementation is restricted to
a maximum of eight 32-bit parameters. On TNS/R or TNS platforms, a 64-bit parameter can occupy
multiple adjacent slots, but not on TNS/E, where each 32-bit parameter is placed in the lower half of
a 64-bit register. The same restriction makes it impossible to create a valid
VARIABLE/EXTENSIBLE mask.
For TNS threads: Start, Length, ArgStart and ArgLen must be even, and @CB.StackOrigin + Length
must be positive and less than 65536d.
For native threads:
• ArgStart and ArgLen must be multiples of 4
• For swapped threads, Start must be a multiple of 4 on TNS/R or 8 on TNS/E
• For static threads, Start must be a multiple of 8 on TNS/R or 16 on TNS/E
• Length must be less than 32MB and a multiple of 8 on TNS/R or 16 on TNS/E
The FinalProc procedure, which takes one GThread_CB parameter designating the current
(expiring) thread, is further discussed below under "Termination” in Section 2.13.
The caller of this function should typically link the new thread onto its list of threads ready to run.
Subsequent calls to GTHREAD_SWAPIN_SETUP_ (for a swapped thread) and
GTHREAD_LONGJMP_ will "resume" the thread at its beginning, which is a call to the InitialProc.