/sys$common/syshlp/helplib.hlb DCE_THREADS, Application Routines, pthread_create  *Conan The Librarian (sorry for the slow response - running on an old VAX)

  NAME

      pthread_create - Creates a thread object and thread

  SYNOPSIS

      #include <pthread.h>

      int pthread_create( pthread_t              *thread,
                          pthread_attr_t         attr,
                          pthread_startroutine_t start_routine,
                          pthread_addr_t         arg );

  PARAMETERS

      thread                Handle to the thread object created.

      attr                  Thread attributes object that defines the
                            characteristics of the thread being created.
                            If you specify pthread_attr_default, default
                            attributes are used.

      start_routine         Function executed as the new thread's start
                            routine.

      arg                   Address value copied and passed to the
                            thread's start routine.

  DESCRIPTION

  The pthread_create() routine creates a thread object and a thread. A
  thread is a single, sequential flow of control within a program. It is
  the active execution of a designated routine, including any nested rou-
  tine invocations.  A thread object defines and controls the executing
  thread.

      CREATING A THREAD

      Calling this routine sets into motion the following actions:

      o    An internal thread object is created to describe the thread.

      o    The associated executable thread is created with attributes
           specified by the attr parameter (or with default attributes if
           pthread_attr_default is specified).

      o    The thread parameter receives the new thread.

      o    The start_routine function is called when this routine
           completes successfully.

      THREAD EXECUTION

      The thread is created in the ready state and therefore might
      immediately begin  executing  the function specified by the
      start_routine parameter.  The newly created thread begins running
      before pthread_create() completes if the new thread follows the
      SCHED_RR or SCHED_FIFO scheduling policy or has a priority higher
      than the creating thread, or both.  Otherwise, the new thread begins
      running at its turn, which with sufficient processors might also be
      before pthread_create() returns.

      The start_routine parameter is passed a copy of the arg  parameter.
      The value of the arg parameter is unspecified.

      The thread object exists until the pthread_detach() routine is called
      or the thread terminates, whichever occurs last.

      The synchronization between the caller of pthread_create() and the
      newly created  thread is through the use of the pthread_join() routine
      (or any other mutexes or condition variables they agree to use).

      TERMINATING A THREAD

      A thread terminates when one of the following events occurs:

      o    The thread returns from its start routine.

      o    The thread exits (within a routine) as the result of calling
           the pthread_exit() routine.

      o    The thread is canceled.

      WHEN A THREAD TERMINATES

      The following actions are performed when a thread terminates:

      o    If the thread terminates by returning from its start routine
           or calling pthread_exit(), the return value is copied into the
           thread object.  If the start routine returns normally and the
           start routine is a procedure that does not return a value, then
           the result obtained by pthread_join() is unpredictable. If the
           thread has been cancelled, a return value of -1 is copied into
           the thread object.  The return value can be retrieved by other
           threads by calling the pthread_join() routine.

      o    A destructor for each thread-specific data point is removed
           from the list of destructors for this thread and then is called.
           This step destroys all the thread-specific data associated with
           the current thread.

      o    Each cleanup handler that has been declared by
           pthread_cleanup_push() and not yet removed by
           pthread_cleanup_pop() is called. The most recently pushed
           handler is called first.

      o    A flag is set in the thread object indicating that the thread
           has terminated. This flag must be set in order for callers of
           pthread_join() to return from the call.

      o    A broadcast is made so that all threads currently waiting in a
           call to pthread_join() can return from the call.

      o    The thread object is marked to indicate that it is no longer
           needed by the thread itself. A check is made to determine if
           the thread object is no longer needed by other threads; that is,
           if pthread_detach() has been called. If that routine is called,
           then the thread object is deallocated.

  RETURN VALUES

  Upon successful completion, this routine stores the  identifier  of  the
  created  thread  at  thread  and  returns 0. Otherwise, a value of -1 is
  returned and no thread is created, the contents of thread are undefined,
  and errno may be set to one of the following values:

    Return   Error      Description
    __________________________________________________
     0                  Successful completion.

    -1      [EAGAIN]    The system lacks the necessary resources
                        to create another thread.

    -1      [ENOMEM]    Insufficient memory exists to create the
                        thread object. This is not a temporary
                        condition.

  RELATED INFORMATION

      FUNCTIONS: pthread_attr_create
                 pthread_cancel
                 pthread_detach
                 pthread_exit
                 pthread_join