Digital

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 start_routine ,
pthread_addr_t arg );

PARAMETERS

threadThread object created. 

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

start_routineFunction executed as the new thread’s start routine. 

argAddress value copied and passed to the thread’s start routine. 

DESCRIPTION

This 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 routine invocations.  A thread object defines and controls the executing thread. 

Calling this routine sets into motion the following actions:

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

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

       •The thread parameter receives the new thread. 

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

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 will begin 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 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). 

A thread terminates when one of the following events occurs:

       •The thread returns from its start routine. 

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

       •The thread is cancelled. 

The following actions are performed when a thread terminates:

       •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. 

       •Each per-thread context destructor is removed from the list of destructors for this thread and then is called. This step destroys all the per-thread context associated with the current thread. 

       •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. 

       •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. 

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

       •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 has been called, then the thread object is deallocated. 

RETURN VALUES

If an error condition occurs, no thread is created, the contents of thread are undefined, and this routine returns −1 and sets errno to the corresponding error value. Possible return values are as follows:

RELATED INFORMATION

pthread_attr_create(3), pthread_cancel(3), pthread_detach(3), pthread_exit(3), pthread_join(3)