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 retri-
-eved 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