|
|
pthread_create(3)
Contents
|
pthread_create - Creates a thread
#include <pthread.h>
int pthread_create(
pthread_t *thread,
const pthread_attr_t *attr,
void * (*start_routine)(void *),
void *arg );
DECthreads POSIX 1003.1c Library (libpthread.so)
Interfaces documented on this reference page conform to
industry standards as follows:
IEEE Std 1003.1c-1995, POSIX System Application Program
Interface
Location for thread object to be created. Thread
attributes object that defines the characteristics of the
thread being created. If you specify NULL, default
attributes are used. Function executed as the new
thread's start routine. Address value copied and passed
to the thread's start routine.
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: DECthreads 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 DECthreads
platforms.) 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 [Toc] [Back]
DECthreads creates a thread in the "ready" state and prepares
the thread to begin executing its start routine, the
function passed to pthread_create(3) 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(3) can synchronize with the new thread
using the pthread_join(3) routine or using any mutually
agreed upon mutexes or condition variables.
For the duration of the new thread's existence, DECthreads
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(3)
or pthread_join(3) for the thread. Termination is
explained in the next section (see Thread Termination).
DECthreads assigns each new thread a thread identifier,
which DECthreads writes into the address specified as the
pthread_create(3) routine's thread argument. DECthreads
writes the new thread's thread identifier 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(3) 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(3) your program must use the
pthread_attr_setinheritsched(3) 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: The signal mask is inherited from the
creating thread. The set of signals pending for the new
thread is empty.
If pthread_create(3) fails, no new thread is created, and
the contents of the location referenced by thread are
undefined.
Thread Termination [Toc] [Back]
A thread terminates when one of the following events
occurs: The thread returns from its start routine. The
thread calls the pthread_exit(3) routine. The thread is
canceled.
When a thread terminates, DECthreads performs these
actions: DECthreads writes a return value (if one is
available) into the terminated thread's thread object, as
follows: If the thread has been canceled, DECthreads
writes the value PTHREAD_CANCELED into the thread's thread
object. If the thread terminated by returning from its
start routine, DECthreads copies the return value from the
start routine (if one is available) into the thread's
thread object. Alternatively, if the thread explicitly
called pthread_exit(3), DECthreads stores the value
received in the value_ptr argument (from pthread_exit(3))
into the thread's thread object. Another thread can
obtain this return value by joining with the terminated
thread (using pthread_join(3)). 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.
If the termination results from a cancellation request or
a call to pthread_exit(3), DECthreads calls, in turn, each
cleanup handler that this thread declared (using
pthread_cleanup_push(3)) and that is not yet removed
(using pthread_cleanup_pop(3)). (DECthreads also transfers
control to any appropriate CATCH, CATCH_ALL, or FINALLY
blocks. DECthreads 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. To exit the terminated
thread due to a call to pthread_exit(3), DECthreads raises
the pthread_exit_e exception. To exit the terminated
thread due to cancellation, DECthreads raises the
pthread_cancel_e exception. Your program can use the DECthreads
exception package to operate on the generated
exception. (In particular, note that the practice of using
CATCH handlers in place of pthread_cleanup_push(3) is not
portable.) For each of the terminated thread's threadspecific
data keys that has a non-NULL value: DECthreads
sets the thread's value for the corresponding key to NULL.
In turn, DECthreads calls each thread-specific data
destructor function in this multithreaded process's list
of destructors. DECthreads repeats 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. DECthreads awakens
the thread (if there is one) that is currently waiting to
join with the terminated thread. That is, DECthreads awakens
the thread that is waiting in a call to
pthread_join(3). If the thread is already detached, DECthreads
destroys its thread object. Otherwise, the thread
continues to exist until detached or joined with.
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: Successful completion. 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. The
value specified by attr is invalid. Insufficient memory
exists to create a thread. The caller does not have the
appropriate permission to create a thread with the specified
attributes.
None
Functions: pthread_atfork(3), pthread_attr_destroy(3),
pthread_attr_init(3), pthread_attr_setdetachstate(3),
pthread_attr_setinheritsched(3), pthread_attr_setschedparam(3), pthread_attr_setschedpolicy(3),
pthread_attr_setstacksize(3), pthread_cancel(3),
pthread_detach(3), pthread_exit(3), pthread_join(3)
Manuals: Guide to DECthreads and Programmer's Guide
pthread_create(3)
[ Back ] |
