Creates a thread.
1 – C Binding
#include <pthread.h>
int
pthread_create (
pthread_t *thread,
const pthread_attr_t *attr,
void * (*start_routine) (void *),
void *arg);
2 – Arguments
thread
Location for thread object to be 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.
3 – Description
This routine creates 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.
Successful execution of this routine includes the following
actions:
o The Threads Library creates a thread object to describe
and control the thread. The thread object includes a thread
environment block (TEB) that programs can use, with care. (See
the <sys/types.h> header file on Tru64 UNIX, or the pthread.h
header file on other platforms.)
o The thread argument receives an identifier for the new thread.
o An executable thread is created with attributes specified
by the attr argument (or with default attributes if NULL is
specified).
Thread Creation
The Threads Library creates a thread in the ready state and
prepares the thread to begin executing its start routine,
the function passed to pthread_create() as the start_routine
argument. Depending on the presence of other threads and their
scheduling and priority attributes, the new thread might start
executing immediately. The new thread can also preempt its
creator, depending on the two threads' respective scheduling
and priority attributes. The caller of pthread_create() can
synchronize with the new thread using the pthread_join() routine
or using any mutually agreed upon mutexes, condition variables or
read-write locks.
For the duration of the new thread's existence, the Threads
Library maintains and manages the thread object and other thread
state overhead. A thread exists until it is both terminated and
detached. A thread is detached when created if the detachstate
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 Threads Library assigns each new thread a thread identifier,
which is written into the address specified as the pthread_
create() routine's thread argument. The new thread's thread
identifier is written before the new thread executes.
By default, the new thread's scheduling policy and priority
are inherited from the creating thread-that is, by default,
the pthread_create() routine ignores the scheduling policy and
priority set in the specified thread attributes object. Thus,
to create a thread that is subject to the scheduling policy and
priority set in the specified thread attributes object, before
calling pthread_create(), your program must use the pthread_attr_
setinheritsched() routine to set the inherit thread attributes
object's scheduling attribute to PTHREAD_EXPLICIT_SCHED.
On Tru64 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:
o The thread returns from its start routine.
o The thread calls the pthread_exit() routine.
o The thread is canceled.
When a thread terminates, the following actions are performed:
1. A return value (if one is available) is written into the
terminated thread's thread object, as follows:
o If the thread has been canceled, the value PTHREAD_CANCELED
is written into the thread's thread object.
o If the thread terminated by returning from its start
routine, the return value is copied from the start routine
(if one is available) into the thread's thread object.
Alternatively, if the thread explicitly called pthread_
exit(), the value received in the value_ptr argument (from
pthread_exit()) is stored in the thread's thread object.
Another thread can obtain this return value by joining with
the terminated thread (using pthread_join()).
NOTE
If the thread terminated by returning from its start
routine normally and the start routine does not provide a
return value, the results obtained by joining with that
thread are unpredictable.
2. If the termination results from a cancelation request or a
call to pthread_exit(), the Threads Library calls, in turn,
each cleanup handler that this thread declared (using pthread_
cleanup_push()) and that is not yet removed (using pthread_
cleanup_pop()). (The Threads Library also transfers control to
any appropriate CATCH, CATCH_ALL, or FINALLY blocks .)
The Threads Library calls the terminated thread's most
recently pushed cleanup handler first.
For C++ programmers: At normal exit from a thread, your
program will call the appropriate destructor functions, just
as if an exception had been raised.
3. To exit the terminated thread due to a call to pthread_exit(),
the Threads Library raises the pthread_exit_e exception. To
exit the terminated thread due to cancelation, the Threads
Library raises the pthread_cancel_e exception.
Your program can use the exception package to operate on the
generated exception. (In particular, note that the practice of
using CATCH handlers in place of pthread_cleanup_push() is not
portable.)
4. For each of the terminated thread's thread-specific data keys
that has a non-NULL value:
o The thread's value for the corresponding key is set to
NULL.
o Call each thread-specific data destructor function in this
multithreaded process' list of destructors.
Repeat this step until all thread-specific data values in the
thread are NULL, or for up to a number of iterations equal to
PTHREAD_DESTRUCTOR_ITERATIONS. This destroys all thread-
specific data associated with the terminated thread.
5. Awaken the thread (if there is one) that is currently waiting
to join with the terminated thread. That is, awaken the thread
that is waiting in a call to pthread_join().
6. If the thread is already detached, destroy its thread object.
Otherwise, the thread continues to exist until detached or
joined with.
4 – Return Values
If an error condition occurs, no thread is created, the contents
of thread are undefined, and this routine returns an integer
value indicating the type of error. Possible return values are as
follows:
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 not a valid attributes
block.
[ENOMEM] Insufficient memory exists to create a thread.
[EPERM] The caller does not have the appropriate permission
to create a thread with the specified attributes.
5 – 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()