pthread_create

Creates a thread.

Syntax

pthread_create(
               thread,
               attr,
               start_routine,
               arg );
 



Argument         Data Type               Access

thread           opaque pthread_t        write

attr             opaque pthread_attr_t   read

start_routine    procedure               read

arg              user_arg                read

C Binding

#include 


int
pthread_create (
         pthread_t   *thread,
         const pthread_attr_t   *attr,
         void *   (*start_routine) (void *),
         void   *arg);

Arguments

thread

Thread object created.

attr

Thread attributes object that defines the characteristics of the thread being created. If you specify NULL, 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

Successful execution of this routine includes the following actions:

• An internal thread object is created to describe and control the thread. The thread object includes a Thread Environment Block (TEB) that programs can use (with care).

• The thread argument receives an identifier for the new thread.

• An executable thread is created with attributes specified by the attr argument (or with default attributes if NULL is specified).

Thread Creation

A thread is created in the ready state to begin executing the function specified by the start_routine argument. The new thread may execute immediately. The newly created thread may preempt its creator, depending on scheduling policy and priority. The thread identifier (pthread_t) specified in pthread_create will be written before the new thread executes.

The new thread's scheduling policy and priority are, by default, inherited from the creating thread-the scheduling policy and priority set in the attributes object are ignored. To create a thread using the scheduling policy and priority set in the attributes object, you must first disable the inherit scheduling attribute by calling pthread_attr_setinheritsched before calling pthread_create.

The thread exists until it is both terminated and detached. A thread is detached when created if the detach state attribute of its thread object is set to PTHREAD_CREATE_DETACHED. It is also detached after any thread returns successfully from calling pthread_detach or pthread_join for the thread. Termination is explained in the next section (see Thread Termination).

The caller of pthread_create can synchronize with the newly created thread through the use of the pthread_join routine, or any other mutexes or condition variables they agree to use.

On Digital UNIX, the signal state of the new thread is initialized as follows:

1. The signal mask is inherited from the creating thread.

2. The set of signals pending for the new thread is empty.

If pthread_create fails, no new thread is created, and the contents of the location referenced by thread are undefined.

Thread Termination

A thread terminates when one of the following events occurs:

• The thread returns from its start routine.

• An exception is raised (or re-raised) in the thread during execution, and the exception is not handled.

• The thread calls the pthread_exit routine.

• The thread is canceled.

The following actions are performed when a thread terminates:

• If the thread has been canceled, a return value of PTHREAD_CANCELED is copied into the thread object. If the thread terminated by returning from its start routine or calling pthread_exit, the return value is copied into the thread object. The return value can be retrieved by other threads by calling the pthread_join routine.

  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 termination results from a cancellation, an unhandled exception, or a call to pthread_exit, each cleanup handler that has been declared by pthread_cleanup_push and not yet removed by pthread_cleanup_pop is called. Cleanup handlers are called in order, starting with the most recently pushed handler.

• For each thread-specific data key for which the thread has a non-NULL value, the destructor routine (if available) is called. Destructors are called in unspecified order. Before each destructor is called, the thread's value for the corresponding key is set to NULL. This step repeats until all thread-specific data values in the thread are NULL, or for up to four iterations (PTHREAD_DESTRUCTOR_ITERATIONS).

• The thread waiting in a call to pthread_join, if any, is awakened.

• The thread object is marked to indicate that it is no longer needed by the thread itself. A check is made to determine whether the thread is already detached. If it is detached, then the thread object is released.

Return Values

Return        Description

0             Successful completion.

[EAGAIN]      The system lacks the necessary resources to create
              another thread, or the system-imposed limit on the
              total number of threads under execution by a single
              user is exceeded.

[EINVAL]      The value specified by attr is invalid.

[ENOMEM]      Insufficient enough memory exists to create a thread.

[EPERM]       The caller does not have the appropriate permission to
              create a thread with the specified attributes.

Associated Routines

   pthread_atfork
   pthread_attr_destroy
   pthread_attr_init
   pthread_attr_setdetachstate
   pthread_attr_setinheritsched
   pthread_attr_setschedparam
   pthread_attr_setschedpolicy
   pthread_attr_setstacksize
   pthread_cancel
   pthread_detach
   pthread_exit
   pthread_join