pthread(3T)                                                     pthread(3T)
                               Pthread Library

 NAME
      pthread - Introduction To POSIX.1c Threads

 DESCRIPTION
      The POSIX.1c library developed by HP enables the creation of processes
      that can exploit application and multi-processor platform parallelism.
      The pthread library libpthread consists of over 90 standardized
      interfaces for developing concurrent applications and synchronizing
      their actions within processes or between them.  This manual page
      presents an overview of libpthread including terminology and how to
      compile and link programs which use threads.

 COMPILATION SUMMARY
      A multi-threaded application must define the appropriate POSIX
      revision level (199506) at compile time and link against the pthread
      library via -lpthread.  For example:

           cc -D_POSIX_C_SOURCE=199506L -o myapp myapp.c -lpthread

      All program sources must also include the header file <pthread.h>.

      Note: When explicitly specifying ANSI compilation (via "-Aa"),
      defining the POSIX revision level restricts the program to using
      interfaces within the POSIX namespaces.  If interfaces in the larger
      X/Open namespace are to be called, either of the compiler options,
      -D_XOPEN_SOURCE_EXTENDED or -D_HPUX_SOURCE, must be specified in
      addition to -D_POSIX_C_SOURCE=199506L.  Alternatively, compiling with
      -Ae (or not specifying "-A") will implicitly specify -D_HPUX_SOURCE.

      Note: Some documentation will recommend the use of -D_REENTRANT for
      compilation.  While this also functions properly, it is considered an
      obsolescent form.

 THREAD OVERVIEW
      A thread is an independent flow of control within a process, composed
      of a context (which includes a register set and a program counter) and
      a sequence of instructions to execute.

      All processes consist of at least one thread.  Multi-threaded
      processes contain several threads.  All threads share the common
      address space allocated for the process.  A program using the POSIX
      pthread APIs creates and manipulates what are called user threads.  A
      kernel thread is a kernel-schedulable entity which may support one or
      more user threads.  Currently, the HP-UX threads implementation
      supports only a one-to-one mapping between user and kernel threads.

      Each thread is assigned a unique identifier of type pthread_t upon
      creation.  The thread id is a process-private value and
      implementation-dependent.  It is considered to be an opaque handle for
      the thread.  Its value should not be used by the application.

 Hewlett-Packard Company            - 1 -     HP-UX Release 11.00: June 1998

 pthread(3T)                                                     pthread(3T)
                               Pthread Library

 NOTES ON INTERFACES
      The HP-UX system provides some non-standard extensions to the pthread
      API.  These will always have a distinguishing suffix of _np or _NP
      (non-portable).

      The programmer should always consult the manpages for the functions
      being used.  Some standard-specified functions are not available or
      may have no effect in some implementations.

 THREAD CREATION/DESTRUCTION
      A program creates a thread using the pthread_create() function.  When
      the thread has completed its work, it may optionally call the
      pthread_exit() function, or simply return from its initial function.
      A thread can detect the completion of another by using the
      pthread_join() function.

      pthread_create()         Creates a thread and assigns a unique
                               identifier, pthread_t.  The caller provides a
                               function which will be executed by the
                               thread.  Optionally, the call may explicitly
                               specify some attributes for the thread (see
                               PTHREAD ATTRIBUTES below).

      pthread_exit()           Called by a thread when it completes.  This
                               function does not return.

      pthread_join()           This is analogous to wait(), but for
                               pthreads.  Any thread may join any other
                               thread in the process, there is no
                               parent/child relationship.  It returns when a
                               specified thread terminates, and the thread
                               resources have been reaped.

      pthread_detach()         Makes it unnecessary to "join" the thread.
                               Thread resources are reaped by the system at
                               the time the thread terminates.

 PTHREAD ATTRIBUTES
      A set of thread attributes may be provided to pthread_create().  Any
      changes from default values must be made to the attribute set before
      the call to pthread_create() is made.  Subsequent changes to the
      attribute set do not affect the created thread.  However, the
      attribute set may be used in multiple pthread_create() calls.

      Note that only the "detachstate", "schedparam", "schedpolicy", and
      "processor" attributes of a thread may be effected subsequent to
      thread creation.  However, this is done via the pthread_detach(),
      pthread_setschedparam(), and pthread_processor_bind_np() functions,
      respectively.

      pthread_attr_init()                Initializes an attribute set for

 Hewlett-Packard Company            - 2 -     HP-UX Release 11.00: June 1998

 pthread(3T)                                                     pthread(3T)
                               Pthread Library

                                         use in the pthread_create() call.

      pthread_attr_destroy()             Destroys the content of an
                                         attribute set.

      pthread_attr_getdetachstate(),
      pthread_attr_getguardsize(),
      pthread_attr_getinheritsched(),
      pthread_attr_getprocessor_np(),
      pthread_attr_getschedparam(),
      pthread_attr_getschedpolicy(),
      pthread_attr_getscope(),
      pthread_attr_getstackaddr(),
      pthread_attr_getstacksize(),
      pthread_attr_setdetachstate(),
      pthread_attr_setguardsize(),
      pthread_attr_setinheritsched(),
      pthread_attr_setprocessor_np(),
      pthread_attr_setschedparam(),
      pthread_attr_setschedpolicy(),
      pthread_attr_setscope(),
      pthread_attr_setstackaddr(),
      pthread_attr_setstacksize()

           These pthread_attr_get/set<attribute>() functions get/set the
           associated attribute in the attribute set.  See the manpages for
           these functions for descriptions of the attributes.

      pthread_default_stacksize_np()
           This is used to set the default stacksize for threads created in
           subsequent attribute set initializations (calls to
           pthread_attr_init()) or in pthread_create() where no attributes
           are supplied.

 CANCELLATION
      Certain applications may desire to terminate a particular thread
      without causing the entire process to exit.  A thread may be canceled
      by another thread in the same process while the cancellation target
      thread executes a system call or particular library routine.

      When a thread issues a cancel request against another thread, the
      target thread can check to see if a request is pending against it via
      the pthread_testcancel() interface. When called with a request
      pending, the target thread terminates after executing any cleanup
      handlers which may have been installed.  Cleanup handlers may be used
      to delete any dynamic storage allocated by the canceled thread, to
      unlock a mutex, or other operations.

      Typically, the cancellation type for a thread is deferred.  That is,
      cancellation requests are held pending until the thread reaches a
      cancellationpoint which is simply one of a list of library functions

 Hewlett-Packard Company            - 3 -     HP-UX Release 11.00: June 1998

 pthread(3T)                                                     pthread(3T)
                               Pthread Library

      and system calls (see lists below).

      The thread may set its cancellation type to asynchronous.  In this
      case cancellation requests are acted upon at any time.  This can be
      used effectively in compute-bound threads which do not call any
      functions that are cancellation points.

      pthread_cancel()              Cancel execution of a given thread.

      pthread_testcancel()          Called by a thread to process pending
                                    cancel requests.

      pthread_setcancelstate(),
      pthread_setcanceltype()

           Set the characteristics of cancellation for the thread.
           Cancellation may be enabled or disabled, or it may be synchronous
           or deferred.

      pthread_cleanup_pop(),
      pthread_cleanup_push()

           Register or remove cancellation cleanup handlers.

      Cancellation points in the pthread library:

           pthread_testcancel()       pthread_cond_wait()
           pthread_cond_timedwait()   pthread_join()

      System functions which are always cancellation points:

           accept()          aio_suspend()   close()        connect()
           creat()           dup2()          *fcntl()       fsync()
           getdirentries()   getmsg()        getpmsg()      ioctl()
           lockf()           lockf64()       lseek()        lseek64()
           mq_receive()      mq_send()       msgrcv()       msgsnd()
           msync()           nanosleep()     open()         pause()
           poll()            putmsg()        putpmsg()      read()
           readv()           recv()          recvfrom()     recvmsg()
           rename()          select()        semop()        send()
           sendmsg()         sendto()        sigsuspend()   sigtimedwait()
           sigwait()         sigwaitinfo()   socket()       system()
           wait()            wait3()         waitid()       waitpid()
           write()           writev()

           * fcntl() is a cancellation point only with the F_SETLK command.

      For the following libc functions, whether the thread is cancelled
      depends upon what action is performed while executing the function.

 Hewlett-Packard Company            - 4 -     HP-UX Release 11.00: June 1998

 pthread(3T)                                                     pthread(3T)
                               Pthread Library

      If the thread blocks while inside the function, a cancellation point
      is created (i.e., the thread may be cancelled).  Note: Other libraries
      may have cancellation points.  Check the associated documentation for
      details.

           blclose()            blget()           blopen()
           blread()             blset()           catclose()
           catgets()            catopen()         closedir()
           closelog()           creat64()         ctermid()
           cuserid()            dbm_close()       dbm_delete()
           dbm_fetch()          dbm_firstkey()    dbm_nextkey()
           dbm_open()           dbm_store()       dbmclose()
           endexportent()       endfsent()        endgrent()
           endhostent()         endnetent()       endnetgrent()
           endprotoent()        endpwent()        endservent()
           endutxent()          fclose()          fflush()
           fgetc()              fgetgrent()       fgetpos()
           fgetpos64()          fgetpwent()       fgets()
           fgetwc()             fgetws()          fmtmsg()
           fopen()              fopen64()         fprintf()
           fputc()              fputs()           fputwc()
           fputws()             fread()           freopen()
           freopen64()          fsetpos()         fsetpos64()
           ftell()              ftello()          ftello64()
           ftw()                ftw64()           fwrite()
           getc()               getc_unlocked()   getchar()
           getchar_unlocked()   getcwd()          getdate()
           getgrent()           getgrgid()        getgrgid_r()
           getgrnam()           getgrnam_r()      gethostbyaddr()
           gethostbyname()      gethostent()      getlogin()
           getlogin_r()         getopt()          getpass()
           getpw()              getpwent()        getpwnam()
           getpwnam_r()         getpwuid()        getpwuid_r()
           gets()               getservbyname()   getservbyport()
           getservent()         gettxt()          getusershell()
           getutent()           getutid()         getutline()
           getutxent()          getutxid()        getutxline()
           getw()               getwc()           getwchr()
           getwd()              glob()            grantpt()
           iconv_close()        iconv_open()      initgroups()
           lckpwdf()            mkstemp()         msem_lock()
           nftw()               nftw2()           nftw64()
           nlist()              open64()          opendir()
           openlog()            pclose()          perror()
           pfmt()               popen()           prealloc()
           prealloc64()         printf()          putc()
           putc_unlocked()      putchar()         putchar_unlocked()
           putpwent()           puts()            pututline()
           pututxline()         putw()            putwc()
           putwchar()           putws()           readdir()

           readdir_r()          realpath()        remove()
           rewind()             rewinddir()       scandir()
           scanf()              seekdir()         setgrent()
           sethostent()         setnetent()       setnetgrent()
           setprotoent()        setpwent()        setservent()
           setusershell()       setutent()        setutxent()
           sigpause()           sleep()           strerror()
           syslog()             tcdrain()         tell()
           tmpfile()            tmpfile64()       tmpnam()
           ttyname()            ttyname_r()       ttyslot()
           ulckpwdf()           ungetc()          ungetwc()
           usleep()             vfprintf()        vfscanf()
           vprintf()            vscanf()          vsprintf()
           vsscanf()            wordexp()         wordfree()

      NOTE1: The above functions may not be fully supported or may be
      considered obsolete.  Consult individual manpages for more info.

      NOTE2: The list of cancellation points will vary from release to
      release.  In general, if a function can return with an EINTR error,
      chances are that it is a cancellation point.

 SCHEDULING
      Threads may individually control their scheduling policy and
      priorities.  Threads may also suspend their own execution, or that of
      other threads.  Finally, threads are given some control over
      allocation of processor resources.

      pthread_suspend()        This function is used to temporarily stop the
                               execution of a thread.

      pthread_continue(),
      pthread_resume_np()

           These functions cause a previously suspended thread to continue
           execution.

      pthread_num_processor_np(),
      pthread_processor_bind_np(),
      pthread_processor_id_np()

           These functions are used to interrogate processor configuration
           and to bind a thread to a specific processor.

      pthread_getconcurrency(),
      pthread_setconcurrency()

           These functions are used to control the actual concurrency for
           unbound threads.

      pthread_getschedparam(),
      pthread_setschedparam()

           These functions are used to manipulate the scheduling policy and
           priority for a thread.

      sched_get_priority_max(),
      sched_get_priority_min()

 Hewlett-Packard Company            - 6 -     HP-UX Release 11.00: June 1998

 pthread(3T)                                                     pthread(3T)
                               Pthread Library

           These functions are used to interrogate the priority range for a
           given scheduling policy.

      sched_yield         This function is used by a thread to yield the
                          processor to other threads of equal or greater
                          priority.

 COMMUNICATION & SYNCHRONIZATION
      Multi-threaded applications concurrently execute instructions.  Access
      to process-wide (or interprocess) shared resources (memory, file
      descriptors, etc.) requires mechanisms for coordination or
      synchronization among threads.  The libpthread library offers
      synchronization primitives necessary to create a deterministic
      application.  A multi-threaded application ensures determinism by
      forcing asynchronous thread contexts to synchronize, or serialize,
      access to data structures and resources managed and manipulated during
      run-time.  These are mutual-exclusion (mutex) locks, condition
      variables, and read-write locks.  The HP-UX operating system also
      provides POSIX semaphores (see next section).

      Mutexes furnish the means to exclusively guard data structures from
      concurrent modification.  Their protocol precludes more than one
      thread which has locked the mutex from changing the contents of the
      protected structure until the locker performs an analogous mutex
      unlock.  A mutex can be initialized in two ways: by a call to
      pthread_mutex_init(); or by assignment of PTHREAD_MUTEX_INITIALIZER.

      Condition Variables are used by a thread to wait for the occurrence of
      some event.  A thread detecting or causing such an event can signal or
      broadcast that occurrence to the waiting thread or threads.

      Read-Write locks permit concurrent read access by multiple threads to
      structures guarded by a read-write lock, but write access by only a
      single thread.

      pthread_mutex_init(),
      pthread_mutex_destroy()

           Initialize/destroy contents of a mutex lock.

      pthread_mutex_lock(),
      pthread_mutex_trylock(),
      pthread_mutex_unlock()

           Lock/unlock a mutex.

      pthread_mutex_getprioceiling(),
      pthread_mutex_setprioceiling()

           Manipulate mutex locking priorities.

 Hewlett-Packard Company            - 7 -     HP-UX Release 11.00: June 1998

 pthread(3T)                                                     pthread(3T)
                               Pthread Library

      pthread_mutexattr_init(),
      pthread_mutexattr_destroy(),
      pthread_mutexattr_getprioceiling(),
      pthread_mutexattr_getprotocol(),
      pthread_mutexattr_getpshared(),
      pthread_mutexattr_gettype(),
      pthread_mutexattr_getspin_np(),
      pthread_mutexattr_setprioceiling(),
      pthread_mutexattr_setprotocol(),
      pthread_mutexattr_setpshared(),
      pthread_mutexattr_settype(),
      pthread_mutexattr_setspin_np()

           Manage mutex attributes used for pthread_mutex_init().  Only the
           "prioceiling" attribute can be changed for an exiting mutex.

      pthread_mutex_getyieldfreq_np(),
      pthread_mutex_setyieldfreq_np()

           These functions, together with the spin attributes, are used to
           tune mutex performance to the specific application.

      pthread_cond_init(),
      pthread_cond_destroy()

           Initialize/destroy contents of a read-write lock.

      pthread_cond_signal(),
      pthread_cond_broadcast(),
      pthread_cond_timedwait(),
      pthread_cond_wait()

           Wait upon or signal occurrence of a condition variable.

      pthread_condattr_init(),
      pthread_condattr_destroy(),
      pthread_condattr_getpshared(),
      pthread_condattr_setpshared()

           Manage condition variable attributes used for
           pthread_cond_init().

      pthread_rwlock_init(),
      pthread_rwlock_destroy()

           Initialize/destroy contents of a read-write lock.

      pthread_rwlock_rdlock(),
      pthread_rwlock_tryrdlock(),
      pthread_rwlock_wrlock(),
      pthread_rwlock_trywrlock(),

 Hewlett-Packard Company            - 8 -     HP-UX Release 11.00: June 1998

 pthread(3T)                                                     pthread(3T)
                               Pthread Library

      pthread_rwlock_unlock()

           Lock/unlock a read-write lock.

      pthread_rwlockattr_init(),
      pthread_rwlockattr_destroy(),
      pthread_rwlockattr_getpshared(),
      pthread_rwlockattr_setpshared()

           Manage read-write lock attributes used for pthread_rwlock_init().

    POSIX 1.b SEMAPHORES
      The semaphore functions specified in the POSIX 1.b standard can also
      be used for synchronization in a multithreaded application.

      sem_init(),
      sem_destroy()

           Initialize/destroy contents of a semaphore.

      sem_post(),
      sem_wait(),
      sem_trywait()

           Increment/decrement semaphore value (possibly blocking).

 SIGNALS
      In a multithreaded process, all threads share signal actions.  That
      is, a signal handler established by one thread is used in all threads.
      However, each thread has a separate signal mask, by which it can
      selectively block signals.

      Signals can be sent to other threads within the same process, or to
      other processes.  When a signal is sent to the process, exactly one
      thread which does not have that signal blocked will handle the signal.
      When sent to a thread within the same process, that thread will handle
      the signal, perhaps later if the signal is blocked.  Signals whose
      action is to terminate, stop, or continue will terminate, stop, or
      continue the entire process, respectively, even if directed at a
      particular thread.

      pthread_kill()           Sends a signal to the given thread.

      pthread_sigmask()        Blocks selected signals for the thread.

      sigwait(),
      sigwaitinfo(),
      sigtimedwait()

           These functions synchronously wait for given signals.

 Hewlett-Packard Company            - 9 -     HP-UX Release 11.00: June 1998

 pthread(3T)                                                     pthread(3T)
                               Pthread Library

 THREAD-SPECIFIC DATA
      Thread-specific data (TSD) is global data that is private or specific
      to a thread.  Each thread has a different value for the same thread-
      specific data variable.  The global errno is a perfect example of
      thread-specific global data.

      Each thread-specific data item is associated with a key.  The key is
      shared by all threads.  However, when a thread references the key, it
      references its own private copy of the data.

      pthread_key_create(),
      pthread_key_destroy()

           These functions manage the thread-specific data keys.

      pthread_getspecific(),
      pthread_setspecific()

           These functions retrieve and assign the data value associated
           with a key.

      The HP-UX compiler supports a thread local storage (TLS) storage
      class.  (This is not a POSIX standard feature.)  TLS is identical to
      TSD, except functions are not required to create/set/get values.  TLS
      variables are accessed just like normal global variables.  TLS
      variables can be declared using the following syntax:

            __thread     int     zyx;

      The keyword __thread tells the compiler that zyx is a TLS variable.
      Now each thread can set or get TLS with statements such as:

           zyx = 21;

      Each thread will have a different value associated with zyx.

      TLS variables cannot be statically initialized, all are initially
      zero.  Dynamically loaded libraries (via shl_load()) cannot declare
      (but may use) TLS variables.

      TLS does have a cost in thread creation/termination operations, as TLS
      space for each thread must be allocated and zeroed, regardless of
      whether it ever will use the variables.  If few threads actually use a
      large TLS area, it may be wise to instead use the POSIX TSD (above).

 REENTRANT LIBC & STDIO
      Because they return pointers to library-internal static data, a number
      of libc functions cannot be used in multi-threaded programs.  This is
      because calling these functions in a thread will overwrite the results
      of previous calls in other threads.  Alternate functions, having the
      suffix _r (for reentrant), are provided within libc for threaded

 Hewlett-Packard Company            - 10 -    HP-UX Release 11.00: June 1998

 pthread(3T)                                                     pthread(3T)
                               Pthread Library

      programming.

      Also, some primitives for synchronization of standard I/O operations
      are provided.

      asctime_r(),
      ctime_r(),
      getgrgid_t(),
      getgrnam_r(),
      getlogin_r(),
      getpwnam_r(),
      getpwuid_r(),
      gmtime_t(),
      localtime_r(),
      rand_r(),
      readdir_r(),
      strtok_r(),
      ttyname_r()

           Provide reentrant versions of previously existing libc functions.

      flockfile(),
      ftrylockfile(),
      funlock()

           Provide explicit synchronization for standard I/O streams.

 MISCELLANEOUS FUNCTIONS
      The section summarizes some miscellaneous pthread-related functions
      not covered in the preceding sections.

      pthread_atfork()         Establish special functions to be called just
                               prior to and just subsequent to a fork()
                               operation.

      pthread_equal()          Tests whether two pthread_t values represent
                               the same pthread.

      pthread_once()           Executes given function just once in a
                               process, regardless of how many threads make
                               the same call.  (Useful for one-time data
                               initialization.)

      pthread_self()           Returns identifier (pthread_t) of calling
                               thread.

 THREAD DEBUGGING
      Debugging of multithreaded programs is supported in the standard HP-UX
      debugger, dde.  When any thread is to be stopped due to a debugger
      event, the debugger will stop all threads.  The register state, stack,
      and data for any thread can be interrogated and manipulated.

 Hewlett-Packard Company            - 11 -    HP-UX Release 11.00: June 1998

 pthread(3T)                                                     pthread(3T)
                               Pthread Library

      See the dde(1) manpage and built-in graphical help system for more
      information.

 TRACING FACILITIES
      HP-UX provides a tracing facility for pthread operations.  To use it,
      you must link your application using the tracing version of the
      library:

           cc -D_POSIX_C_SOURCE=199506L -o myapp myapp.c -lpthread_tr -lcl

      When the application is executed, it produces a per-thread file of
      pthread events.  This is used as input to the ttv thread trace
      visualizer facility available in the HP/PAK performance application
      kit.

      There are environment variables defined to control trace data files:

      THR_TRACE_DIR
           Where to place the trace data files. If this is not defined, the
           files go to the current working directory.

      THR_TRACE_SYNC
           By default, trace records are buffered and only written to the
           file when the buffer is full. If this variable is set to any non-
           NULL value, data is immediately written to the trace file.

      THR_TRACE_EVENTS
           By default, all pthread events are traced.  If this variable is
           defined, only the categories defined will be traced. Each
           category is separated by a ':'.  The possible trace categories
           are:

           thread:cond:mutex:rwlock

           For example, to only trace thread and mutex operations set the
           THR_TRACE_EVENTS variable to:

           thread:mutex

      Details of the trace file record format can be found in
      /usr/include/sys/trace_thread.h.

      See the ttv(1) manpage and built-in graphical help system for more
      information on the use of the trace information.

 PERFORMANCE CONSIDERATIONS
      Often, an application is designed to be multithreaded to improve
      performance over its single-threaded counterparts.  However, the
      multithreaded approach requires some attention to issues not always of
      concern in the single-threaded case.  These are issues traditionally
      associated with the programming of multiprocessor systems.

 Hewlett-Packard Company            - 12 -    HP-UX Release 11.00: June 1998

 pthread(3T)                                                     pthread(3T)
                               Pthread Library

      The design must employ a lock granularity appropriate to the data
      structures and access patterns.  Coarse-grained locks, which protect
      relatively large amounts of data, can lead to undesired lock
      contention, reducing the potential parallelism of the application.  On
      the other hand, employing very fine-grained locks, which protect very
      small amounts of data, can consume processor cycles with too much
      locking activity.

      The use of thread-specific data (TSD) or thread-localstorage (TLS)
      must be traded off, as described above (see THREAD-SPECIFIC DATA).

      Mutex spin and yield frequency attributes can be used to tune mutex
      behavior to the application.  See pthread_mutexattr_setspin_np(3T) and
      pthread_mutex_setyieldfreq_np(3T) for more information.

      The default stacksize attribute can be set to improve system thread
      caching behavior.  See pthread_default_stacksize_np(3T) for more
      information.

      Because multiple threads are actually running simultaneously, they can
      be accessing the same data from multiple processors.  The hardware
      processors coordinate their caching of data such that no processor is
      using stale data.  When one processor accesses the data (especially
      for write operations), the other processors must flush the stale data
      from their caches.  If multiple processors repeatedly read/write the
      same data, this can lead to cache-thrashing which slows execution of
      the instruction stream.  This can also occur when threads access
      separate data items which just happen to reside in the same hardware-
      cachable unit (called a cache line).  This latter situation is called
      false-sharing which can be avoided by spacing data such that popular
      items are not stored close together.

 GLOSSARY
      The following definitions were extracted from the text ThreadTime by
      Scott J. Norton and Mark D. DiPasquale, Prentice-Hall, ISBN
      0-13-190067-6, 1996.

    Application Programming Interface (API)
      An interface is the conduit that provides access to an entity or
      communication between entities. In the programming world, an interface
      describes how access (or communication) with a function should take
      place. Specifically, the number of parameters, their names and purpose
      describe how to access a function. An API is the facility that
      provides access to a function.

    Async-Cancel Safe
      A function that may be called by a thread with the cancelability state
      set to PTHREAD_CANCEL_ENABLE and the cancelability type set to
      PTHREAD_CANCEL_ASYNCHRONOUS.  If a thread is canceled in one of these
      functions, no state is left in the function. These functions generally
      do not acquire resources to perform the function's task.

 Hewlett-Packard Company            - 13 -    HP-UX Release 11.00: June 1998

 pthread(3T)                                                     pthread(3T)
                               Pthread Library

    Async-Signal Safe
      An async-signal safe function is a function that may be called by a
      signal handler. Only a restricted set of functions may safely be
      called by a signal handler. These functions are listed in section
      3.3.1.3 of the POSIX.1c standard.

    Asynchronous Signal
      An asynchronous signal is a signal that has been generated due to an
      external event. Signals sent via kill() and signals generated due to
      timer expiration or asynchronous I/O completion are all examples of
      asynchronously generated signals. Asynchronous signals are delivered
      to the process. All signals can be generated asynchronously.

    Atfork Handler
      Application-provided and registered functions that are called before
      and after a fork() operation. These functions generally acquire all
      mutex locks before the fork() and release these mutex locks in both
      the parent and child processes after the fork().

    Atomic Operation
      An operation or sequence of events that is guaranteed to complete as
      if it were one instruction.

    Barrier
      A synchronization primitive that causes a certain number of threads to
      wait or rendezvous at specified points in an application. Barriers are
      used when a application needs to ensure that all threads have
      completed some operation before proceeding onto the next task.

    Bound Thread
      A user thread that is directly bound to a kernel-scheduled entity.
      These threads contain a system scheduling scope and are scheduled
      directly by the kernel.

    Cache Thrashing
      Cache thrashing is a situation in which a thread executes on different
      processors, causing cached data to be moved to and from the different
      processor caches. Cache thrashing can cause severe performance
      degradation.

    Cancellation Cleanup Handler
      An application-provided and registered function that is called when a
      thread is canceled. These functions generally perform thread cleanup
      actions during thread cancellation. These handlers are similar to
      signal handlers.

    Condition Variable
      A condition variable is a synchronization primitive used to allow a
      thread to wait for an event. Condition variables are often used in
      producer-consumer problems where a producer must provide something to
      one or more consumers.

 Hewlett-Packard Company            - 14 -    HP-UX Release 11.00: June 1998

 pthread(3T)                                                     pthread(3T)
                               Pthread Library

    Context Switch
      The act of removing the currently running thread from the processor
      and running another thread. A context switch saves the register state
      of the currently running thread and restores the register state of the
      thread chosen to execute next.

    Critical Section
      A section of code that must complete atomically and uninterrupted. A
      critical section of code is generally one in which some global
      resource (variables, data structures, linked lists, etc.) is modified.
      The operation being performed must complete atomically so that other
      threads do not see the critical section in an inconsistent state.

    Deadlock
      A deadlock occurs when one or more threads can no longer execute. For
      example, thread A holds lock 1 and is blocked on lock 2. Meanwhile,
      thread B holds lock 2 and is blocked on lock 1. Threads A and B are
      permanently deadlocked. Deadlocks can occur with any number of
      resource holding threads. An interactive deadlock involves two or more
      threads. A recursive (or self) deadlock involves only one thread.

    Detached Thread
      A thread whose resources are automatically released by the system when
      the thread terminates. A detached thread cannot be joined by another
      thread. Consequently, detached threads cannot return an exit status.

    Joinable Thread
      A thread whose termination can be waited for by another thread.
      Joinable threads can return an exit status to a joining thread.
      Joinable threads maintain some state after termination until they are
      joined by another thread.

    Kernel Mode
      A mode of operation where all operations are allowed. While a thread
      is executing a system call it is executing in kernel mode.

    Kernel Space
      The kernel program exists in this space. Kernel code is executed in
      this space at the highest privilege level. In general, there are two
      privilege levels: one for user code (user mode) and the other for
      kernel code (kernel mode).

    Kernel Stack
      When a thread makes a system call, it executes in kernel mode. While
      in kernel mode, it does not use the stack allocated for use by the
      application. Instead, a separate kernel stack is used while in the
      system call. Each kernel-scheduled entity, whether a process, kernel
      thread or lightweight process, contains a kernel stack. See Stack for
      a generic description of a stack.

    Kernel Thread

 Hewlett-Packard Company            - 15 -    HP-UX Release 11.00: June 1998

 pthread(3T)                                                     pthread(3T)
                               Pthread Library

      Kernel threads are created by the thread functions in the threads
      library. Kernel threads are kernel-scheduled entities that are visible
      to the operating system kernel. A kernel thread typically supports one
      or more user threads. Kernel threads execute kernel code or system
      calls on behalf of user threads. Some systems may call the equivalent
      of a kernel thread a lightweight process.  See Thread for a generic
      description of a thread.

    Lightweight Process
      A kernel-scheduled entity. Some systems may call the equivalent of a
      lightweight process a kernel thread. Each process contains one or more
      lightweight process. How many lightweight processes a process contains
      depends on whether and how the process is multithreaded. See Thread
      for a generic description of a thread.

    Multiprocessor
      A system with two or more processors (CPUs). Multiprocessors allow
      multithreaded applications to obtain true parallelism.

    Multithreading
      A programming model that allows an application to have multiple
      threads of execution. Multithreading allows an application to have
      concurrency and parallelism (on multiprocessor systems).

    Mutex
      A mutex is a mutual exclusion synchronization primitive. Mutexes
      provide threads with the ability to regulate or serialize access to
      process shared data and resources. When a thread locks a mutex, other
      threads trying to lock the mutex block until the owning thread unlocks
      the mutex.

    POSIX
      Portable Operating System Interface. POSIX defines a set of standards
      that multiple vendors conform to in order to provide for application
      portability. The Pthreads standard (POSIX 1003.1c) provides a set of
      portable multithreading APIs to application developers.

    Priority Inversion
      A situation where a low-priority thread has acquired a resource that
      is needed by a higher priority thread. As the resource cannot be
      acquired, the higher priority thread must wait for the resource. The
      end result is that a low-priority thread blocks a high-priority
      thread.

    Process
      A process can be thought of as a container for one or more threads of
      execution, an address space, and shared process resources. All
      processes have at least one thread. Each thread in the process
      executes within the process' address space. Examples of process-shared
      resources are open file descriptors, message queue descriptors,
      mutexes, and semaphores.

 Hewlett-Packard Company            - 16 -    HP-UX Release 11.00: June 1998

 pthread(3T)                                                     pthread(3T)
                               Pthread Library

    Process Control Block (PCB)
      This structure holds the register context of a process.

    Process Structure
      The operating system maintains a process structure for each process in
      the system. This structure represents the actual process internally in
      the system. A sample of process structure information includes the
      process ID, the process' set of open files, and the signal vector. The
      process structure and the values contained within it are part of the
      context of a process.

    Program Counter (PC)
      The program counter is part of the register context of a process. It
      holds the address of the current instruction to be executed.

    Race Condition
      When the result of two or more threads performing an operation depends
      on unpredictable timing factors, this is a race condition.

    Read-Write Lock
      A read-write lock is a synchronization primitive. Read-write locks
      provide threads with the ability to regulate or serialize access to
      process-shared data and resources. Read-write locks allow multiple
      readers to concurrently acquire the read lock whereas only one writer
      at a time may acquire the write lock. These locks are useful for
      shared data that is mostly read and only rarely written.

    Reentrant Function
      A reentrant function is one that when called by multiple threads,
      behaves as if the function was called serially, one after another, by
      the different threads. These functions may execute in parallel.

    Scheduling Allocation Domain
      The set of processors on which a thread is scheduled. The size of this
      domain may dynamically change over time. Threads may also be moved
      from one domain to another.

    Scheduling Contention Scope
      The scheduling contention scope defines the group of threads that a
      thread competes with for access to resources. The contention scope is
      most often associated with access to a processor. However, this scope
      may also be used when threads compete for other resources. Threads
      with the system scope compete for access to resources with all other
      threads in the system. Threads with the process scope compete for
      access to resources with other process scope threads in the process.

    Scheduling Policy
      A scheduling policy is a set of rules used to determine how and when
      multiple threads are scheduled to execute. The scheduling policy also
      determines how long a thread is allowed to execute.

 Hewlett-Packard Company            - 17 -    HP-UX Release 11.00: June 1998

 pthread(3T)                                                     pthread(3T)
                               Pthread Library

    Scheduling Priority
      A scheduling priority is a numeric priority value assigned to threads
      in certain scheduling policies. Threads with higher priorities are
      given preference when scheduling decisions are made.

    Semaphore
      A semaphore is similar to a mutex. A semaphore regulates access to one
      or more shared objects. A semaphore has a value associated with it.
      The value is generally set to the number of shared resources regulated
      by the semaphore. When a semaphore has a value of one, it is a binary
      semaphore. A mutex is essentially a binary semaphore. When a semaphore
      has a value greater than one, it is known as a counting semaphore.  A
      counting semaphore can be locked by multiple threads simultaneously.
      Each time the semaphore is locked, the value is decremented by one.
      After the value reaches zero, new attempts to lock the semaphore cause
      the locking thread to block until the semaphore is unlocked by another
      thread.

    Shared Object
      A shared object is a tangible entity that exists in the address space
      of a process and is accessible by all threads within the process. In
      the context of multithreaded programming, "shared objects" are global
      variables, file descriptors, and other such objects that require
      access by threads to be synchronized.

    Signal
      A signal is a simplified IPC mechanism that allows a process or thread
      to be notified of an event. Signals can be generated synchronously and
      asynchronously.

    Signal Mask
      A signal mask determines which signals a thread accepts and which ones
      are blocked from delivery. If a synchronous signal is blocked from
      delivery, it is held pending until either the thread unblocks the
      signal or the thread terminates. If an asynchronous signal delivered
      to the process is blocked from delivery by a thread, the signal may be
      handled by a different thread in the process that does not have the
      signal blocked.

    Signal Vector
      A signal vector is a table contained in each process that describes
      the action that should be taken when a signal is delivered to a thread
      within the process. Each signal has one of three potential behaviors:
      ignore the signal, execute a signal-handling function, or perform the
      default action of the signal (usually process termination).

    Single-Threaded
      means that there is only one flow of control (one thread) through the
      program code; only one instruction is executed at a time.

    Spinlock

 Hewlett-Packard Company            - 18 -    HP-UX Release 11.00: June 1998

 pthread(3T)                                                     pthread(3T)
                               Pthread Library

      A synchronization primitive similar to a mutex. If the lock cannot be
      acquired, instead of blocking, the thread wishing to acquire the lock
      spins in a loop until the lock can be acquired. Spinlocks can be
      easily used improperly and can severely degrade performance if used on
      a single processor system.

    Spurious Wakeup
      A spurious wakeup occurs when a thread is incorrectly unblocked, even
      though the event it was waiting for has not occurred. A condition wait
      that is interrupted and returns because the blocked thread received a
      normal signal is an example of a spurious wakeup.

    Stack
      A stack is used by a thread to make function calls (and return from
      those calls), to pass arguments to a function call, and to create the
      space for local variables when in that function call. Bound threads
      have a user stack and a kernel stack. Unbound threads have only a user
      stack.

    Synchronous Signal
      A synchronous signal is a signal that has been generated due to some
      action of a specific thread. For example, when a thread does a divide
      by zero, causes a floating point exception, or executes an illegal
      instruction, a signal is generated synchronously. Synchronous signals
      are delivered to the thread that caused the signal to be sent.

    Traditional Process
      This is a single-threaded entity that can be scheduled to execute on a
      processor.

    Thread
      A thread is an independent flow of control within a process, composed
      of a context (which includes a register set and program counter) and a
      sequence of instructions to execute.

    Thread Local Storage (TLS)
      Thread local storage is essentially thread-specific data requiring
      support from the compilers. With TLS, an application can allocate the
      actual data as thread-specific data rather than using thread-specific
      data keys. Additionally, TLS does not require the thread to make a
      function call to obtain thread-specific data. The thread can access
      the data directly.

    Thread-Safe Function
      A thread-safe function is one that may be safely called by multiple
      threads at the same time. If the function accesses shared data or
      resources, this access is regulated by a mutex or some other form of
      synchronization.

    Thread-Specific Data (TSD)
      Thread-specific data is global data that is specific to a thread. All

 Hewlett-Packard Company            - 19 -    HP-UX Release 11.00: June 1998

 pthread(3T)                                                     pthread(3T)
                               Pthread Library

      threads access the same data variable. However, each thread has its
      own thread-specific value associated with this variable. errno is an
      example of thread-specific data.

    Thread Structure
      The operating system maintains a thread structure for each thread in
      the system. This structure represents the actual thread internally in
      the system. A sample of thread structure information includes the
      thread ID, the scheduling policy and priority, and the signal mask.
      The thread structure and the values contained within it are part of
      the context of a thread.

    User Mode
      A mode of operation where a subset of operations are allowed. While a
      thread is executing an applications code, it is executing in user
      mode. When the thread makes a system call, it changes modes and
      executes in kernel mode until the system call completes.

    User Space
      The user code exists in this space. User code is executed in this
      space at the normal privilege level. In general, there are two
      privilege levels: one for user code (user mode) and the other for
      kernel code (kernel mode).

    User Stack
      When a thread is executing code in user space, it needs to use a stack
      to make function calls, pass parameters, and create local variables.
      While in user mode, a thread does not use the kernel stack. Instead, a
      separate user stack is allocated for use by each user thread. See
      Stack for a generic description of a stack.

    User Thread
      When pthread_create() is called, a user thread is created. Whether a
      kernel-scheduled entity (kernel thread or lightweight process) is also
      created depends on the user thread's scheduling contention scope. When
      a bound thread is created, both a user thread and a kernel-scheduled
      entity are created. When an unbound thread is created, generally only
      a user thread is created. See Thread for a generic description of a
      thread.

 SEE ALSO
      ThreadTime by Scott J. Norton and Mark D. DiPasquale, Prentice-Hall,
      ISBN 0-13-190067-6, 1996.