 |
Index for
Section 3 |
|
 |
Alphabetical
listing for P |
|
 |
Bottom of
page |
|
pthread_create(3)
NAME
pthread_create - Creates a thread
SYNOPSIS
#include <pthread.h>
int pthread_create(
pthread_t *thread,
const pthread_attr_t *attr,
void * (*start_routine)(void *),
void *arg );
LIBRARY
DECthreads POSIX 1003.1c Library (libpthread.so)
STANDARDS
Interfaces documented on this reference page conform to industry standards
as follows:
IEEE Std 1003.1c-1995, POSIX System Application Program Interface
PARAMETERS
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.
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:
· 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
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
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 thread-specific 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.
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:
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 memory exists to create a thread.
[EPERM]
The caller does not have the appropriate permission to create a thread
with the specified attributes.
ERRORS
None
SEE ALSO
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
|
Index for
Section 3 |
|
|
Alphabetical
listing for P |
|
 |
Top of
page |
|