1PTHREAD_CREATE(P) POSIX Programmer's Manual PTHREAD_CREATE(P)
2
6 pthread_create - thread creation
7
9 #include <pthread.h>
10 int pthread_create(pthread_t *restrict thread,
12 const pthread_attr_t *restrict attr,
13 void *(*start_routine)(void*), void *restrict arg);
14
17 The pthread_create() function shall create a new thread, with
18 attributes specified by attr, within a process. If attr is NULL, the
19 default attributes shall be used. If the attributes specified by attr
20 are modified later, the thread's attributes shall not be affected. Upon
21 successful completion, pthread_create() shall store the ID of the cre‐
22 ated thread in the location referenced by thread.
23 The thread is created executing start_routine with arg as its sole
25 argument. If the start_routine returns, the effect shall be as if there
26 was an implicit call to pthread_exit() using the return value of
27 start_routine as the exit status. Note that the thread in which main()
28 was originally invoked differs from this. When it returns from main(),
29 the effect shall be as if there was an implicit call to exit() using
30 the return value of main() as the exit status.
31 The signal state of the new thread shall be initialized as follows:
33 * The signal mask shall be inherited from the creating thread.
35 * The set of signals pending for the new thread shall be empty.
37 The alternate stack shall not be inherited.
39 The floating-point environment shall be inherited from the creating
41 thread.
42 If pthread_create() fails, no new thread is created and the contents of
44 the location referenced by thread are undefined.
45 If _POSIX_THREAD_CPUTIME is defined, the new thread shall have a CPU-
47 time clock accessible, and the initial value of this clock shall be set
48 to zero.
49
51 If successful, the pthread_create() function shall return zero; other‐
52 wise, an error number shall be returned to indicate the error.
53
55 The pthread_create() function shall fail if:
56 EAGAIN The system lacked the necessary resources to create another
58 thread, or the system-imposed limit on the total number of
59 threads in a process {PTHREAD_THREADS_MAX} would be exceeded.
60 EINVAL The value specified by attr is invalid.
62 EPERM The caller does not have appropriate permission to set the
64 required scheduling parameters or scheduling policy.
65 The pthread_create() function shall not return an error code of
68 [EINTR].
69 The following sections are informative.
71
73 None.
74
76 None.
77
79 A suggested alternative to pthread_create() would be to define two sep‐
80 arate operations: create and start. Some applications would find such
81 behavior more natural. Ada, in particular, separates the "creation" of
82 a task from its "activation".
83 Splitting the operation was rejected by the standard developers for
85 many reasons:
86 * The number of calls required to start a thread would increase from
88 one to two and thus place an additional burden on applications that
89 do not require the additional synchronization. The second call, how‐
90 ever, could be avoided by the additional complication of a start-up
91 state attribute.
92 * An extra state would be introduced: "created but not started". This
94 would require the standard to specify the behavior of the thread
95 operations when the target has not yet started executing.
96 * For those applications that require such behavior, it is possible to
98 simulate the two separate steps with the facilities that are cur‐
99 rently provided. The start_routine() can synchronize by waiting on a
100 condition variable that is signaled by the start operation.
101 An Ada implementor can choose to create the thread at either of two
103 points in the Ada program: when the task object is created, or when the
104 task is activated (generally at a "begin"). If the first approach is
105 adopted, the start_routine() needs to wait on a condition variable to
106 receive the order to begin "activation". The second approach requires
107 no such condition variable or extra synchronization. In either
108 approach, a separate Ada task control block would need to be created
109 when the task object is created to hold rendezvous queues, and so on.
110 An extension of the preceding model would be to allow the state of the
112 thread to be modified between the create and start. This would allow
113 the thread attributes object to be eliminated. This has been rejected
114 because:
115 * All state in the thread attributes object has to be able to be set
117 for the thread. This would require the definition of functions to
118 modify thread attributes. There would be no reduction in the number
119 of function calls required to set up the thread. In fact, for an
120 application that creates all threads using identical attributes, the
121 number of function calls required to set up the threads would be
122 dramatically increased. Use of a thread attributes object permits
123 the application to make one set of attribute setting function calls.
124 Otherwise, the set of attribute setting function calls needs to be
125 made for each thread creation.
126 * Depending on the implementation architecture, functions to set
128 thread state would require kernel calls, or for other implementation
129 reasons would not be able to be implemented as macros, thereby
130 increasing the cost of thread creation.
131 * The ability for applications to segregate threads by class would be
133 lost.
134 Another suggested alternative uses a model similar to that for process
136 creation, such as "thread fork". The fork semantics would provide more
137 flexibility and the "create" function can be implemented simply by
138 doing a thread fork followed immediately by a call to the desired
139 "start routine" for the thread. This alternative has these problems:
140 * For many implementations, the entire stack of the calling thread
142 would need to be duplicated, since in many architectures there is no
143 way to determine the size of the calling frame.
144 * Efficiency is reduced since at least some part of the stack has to
146 be copied, even though in most cases the thread never needs the
147 copied context, since it merely calls the desired start routine.
148
150 None.
151
153 fork() , pthread_exit() , pthread_join() , the Base Definitions volume
154 of IEEE Std 1003.1-2001, <pthread.h>
155
157 Portions of this text are reprinted and reproduced in electronic form
158 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
159 -- Portable Operating System Interface (POSIX), The Open Group Base
160 Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
161 Electrical and Electronics Engineers, Inc and The Open Group. In the
162 event of any discrepancy between this version and the original IEEE and
163 The Open Group Standard, the original IEEE and The Open Group Standard
164 is the referee document. The original Standard can be obtained online
165 at http://www.opengroup.org/unix/online.html .
166IEEE/The Open Group 2003 PTHREAD_CREATE(P)