mirror of https://github.com/mkerrisk/man-pages
192 lines
7.2 KiB
Plaintext
192 lines
7.2 KiB
Plaintext
.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
|
|
.TH "PTHREAD_CREATE" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
|
|
.\" pthread_create
|
|
.SH NAME
|
|
pthread_create \- thread creation
|
|
.SH SYNOPSIS
|
|
.LP
|
|
\fB#include <pthread.h>
|
|
.br
|
|
.sp
|
|
int pthread_create(pthread_t *restrict\fP \fIthread\fP\fB,
|
|
.br
|
|
\ \ \ \ \ \ const pthread_attr_t *restrict\fP \fIattr\fP\fB,
|
|
.br
|
|
\ \ \ \ \ \ void *(*\fP\fIstart_routine\fP\fB)(void*), void *restrict\fP
|
|
\fIarg\fP\fB); \fP
|
|
\fB
|
|
.br
|
|
\fP
|
|
.SH DESCRIPTION
|
|
.LP
|
|
The \fIpthread_create\fP() function shall create a new thread, with
|
|
attributes specified by \fIattr\fP, within a process. If
|
|
\fIattr\fP is NULL, the default attributes shall be used. If the attributes
|
|
specified by \fIattr\fP are modified later, the
|
|
thread's attributes shall not be affected. Upon successful completion,
|
|
\fIpthread_create\fP() shall store the ID of the created
|
|
thread in the location referenced by \fIthread\fP.
|
|
.LP
|
|
The thread is created executing \fIstart_routine\fP with \fIarg\fP
|
|
as its sole argument. If the \fIstart_routine\fP returns,
|
|
the effect shall be as if there was an implicit call to \fIpthread_exit\fP()
|
|
using
|
|
the return value of \fIstart_routine\fP as the exit status. Note that
|
|
the thread in which \fImain\fP() was originally invoked
|
|
differs from this. When it returns from \fImain\fP(), the effect shall
|
|
be as if there was an implicit call to \fIexit\fP() using the return
|
|
value of \fImain\fP() as the exit status.
|
|
.LP
|
|
The signal state of the new thread shall be initialized as follows:
|
|
.IP " *" 3
|
|
The signal mask shall be inherited from the creating thread.
|
|
.LP
|
|
.IP " *" 3
|
|
The set of signals pending for the new thread shall be empty.
|
|
.LP
|
|
.LP
|
|
The alternate stack shall not be inherited.
|
|
.LP
|
|
The floating-point environment shall be inherited from the creating
|
|
thread.
|
|
.LP
|
|
If \fIpthread_create\fP() fails, no new thread is created and the
|
|
contents of the location referenced by \fIthread\fP are
|
|
undefined.
|
|
.LP
|
|
If _POSIX_THREAD_CPUTIME is defined, the new thread shall have a CPU-time
|
|
clock accessible, and the initial value of this clock
|
|
shall be set to zero.
|
|
.SH RETURN VALUE
|
|
.LP
|
|
If successful, the \fIpthread_create\fP() function shall return zero;
|
|
otherwise, an error number shall be returned to indicate
|
|
the error.
|
|
.SH ERRORS
|
|
.LP
|
|
The \fIpthread_create\fP() function shall fail if:
|
|
.TP 7
|
|
.B EAGAIN
|
|
The system lacked the necessary resources to create another thread,
|
|
or the system-imposed limit on the total number of threads
|
|
in a process {PTHREAD_THREADS_MAX} would be exceeded.
|
|
.TP 7
|
|
.B EINVAL
|
|
The value specified by \fIattr\fP is invalid.
|
|
.TP 7
|
|
.B EPERM
|
|
The caller does not have appropriate permission to set the required
|
|
scheduling parameters or scheduling policy.
|
|
.sp
|
|
.LP
|
|
The \fIpthread_create\fP() function shall not return an error code
|
|
of [EINTR].
|
|
.LP
|
|
\fIThe following sections are informative.\fP
|
|
.SH EXAMPLES
|
|
.LP
|
|
None.
|
|
.SH APPLICATION USAGE
|
|
.LP
|
|
None.
|
|
.SH RATIONALE
|
|
.LP
|
|
A suggested alternative to \fIpthread_create\fP() would be to define
|
|
two separate operations: create and start. Some
|
|
applications would find such behavior more natural. Ada, in particular,
|
|
separates the "creation" of a task from its
|
|
"activation".
|
|
.LP
|
|
Splitting the operation was rejected by the standard developers for
|
|
many reasons:
|
|
.IP " *" 3
|
|
The number of calls required to start a thread would increase from
|
|
one to two and thus place an additional burden on
|
|
applications that do not require the additional synchronization. The
|
|
second call, however, could be avoided by the additional
|
|
complication of a start-up state attribute.
|
|
.LP
|
|
.IP " *" 3
|
|
An extra state would be introduced: "created but not started". This
|
|
would require the standard to specify the behavior of the
|
|
thread operations when the target has not yet started executing.
|
|
.LP
|
|
.IP " *" 3
|
|
For those applications that require such behavior, it is possible
|
|
to simulate the two separate steps with the facilities that
|
|
are currently provided. The \fIstart_routine\fP() can synchronize
|
|
by waiting on a condition variable that is signaled by the start
|
|
operation.
|
|
.LP
|
|
.LP
|
|
An Ada implementor can choose to create the thread at either of two
|
|
points in the Ada program: when the task object is created,
|
|
or when the task is activated (generally at a "begin"). If the first
|
|
approach is adopted, the \fIstart_routine\fP() needs to
|
|
wait on a condition variable to receive the order to begin "activation".
|
|
The second approach requires no such condition variable
|
|
or extra synchronization. In either approach, a separate Ada task
|
|
control block would need to be created when the task object is
|
|
created to hold rendezvous queues, and so on.
|
|
.LP
|
|
An extension of the preceding model would be to allow the state of
|
|
the thread to be modified between the create and start. This
|
|
would allow the thread attributes object to be eliminated. This has
|
|
been rejected because:
|
|
.IP " *" 3
|
|
All state in the thread attributes object has to be able to be set
|
|
for the thread. This would require the definition of
|
|
functions to modify thread attributes. There would be no reduction
|
|
in the number of function calls required to set up the thread.
|
|
In fact, for an application that creates all threads using identical
|
|
attributes, the number of function calls required to set up
|
|
the threads would be dramatically increased. Use of a thread attributes
|
|
object permits the application to make one set of attribute
|
|
setting function calls. Otherwise, the set of attribute setting function
|
|
calls needs to be made for each thread creation.
|
|
.LP
|
|
.IP " *" 3
|
|
Depending on the implementation architecture, functions to set thread
|
|
state would require kernel calls, or for other
|
|
implementation reasons would not be able to be implemented as macros,
|
|
thereby increasing the cost of thread creation.
|
|
.LP
|
|
.IP " *" 3
|
|
The ability for applications to segregate threads by class would be
|
|
lost.
|
|
.LP
|
|
.LP
|
|
Another suggested alternative uses a model similar to that for process
|
|
creation, such as "thread fork". The fork semantics
|
|
would provide more flexibility and the "create" function can be implemented
|
|
simply by doing a thread fork followed immediately by
|
|
a call to the desired "start routine" for the thread. This alternative
|
|
has these problems:
|
|
.IP " *" 3
|
|
For many implementations, the entire stack of the calling thread would
|
|
need to be duplicated, since in many architectures there
|
|
is no way to determine the size of the calling frame.
|
|
.LP
|
|
.IP " *" 3
|
|
Efficiency is reduced since at least some part of the stack has to
|
|
be copied, even though in most cases the thread never needs
|
|
the copied context, since it merely calls the desired start routine.
|
|
.LP
|
|
.SH FUTURE DIRECTIONS
|
|
.LP
|
|
None.
|
|
.SH SEE ALSO
|
|
.LP
|
|
\fIfork\fP() , \fIpthread_exit\fP() , \fIpthread_join\fP() , the Base
|
|
Definitions volume of IEEE\ Std\ 1003.1-2001, \fI<pthread.h>\fP
|
|
.SH COPYRIGHT
|
|
Portions of this text are reprinted and reproduced in electronic form
|
|
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
|
|
-- Portable Operating System Interface (POSIX), The Open Group Base
|
|
Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
|
|
Electrical and Electronics Engineers, Inc and The Open Group. In the
|
|
event of any discrepancy between this version and the original IEEE and
|
|
The Open Group Standard, the original IEEE and The Open Group Standard
|
|
is the referee document. The original Standard can be obtained online at
|
|
http://www.opengroup.org/unix/online.html .
|