add directory Ref-docs
This commit is contained in:
gohigh
250
Ref-docs/POSIX/susv3/functions/pthread_create.html
Normal file
250
Ref-docs/POSIX/susv3/functions/pthread_create.html
Normal file
@@ -0,0 +1,250 @@
|
||||
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
||||
<html>
|
||||
<head>
|
||||
<meta name="generator" content="HTML Tidy, see www.w3.org">
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
||||
<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group's rhtm tool v1.2.1 -->
|
||||
<!-- Copyright (c) 2001 The Open Group, All Rights Reserved -->
|
||||
<title>pthread_create</title>
|
||||
</head>
|
||||
<body bgcolor="white">
|
||||
<script type="text/javascript" language="JavaScript" src="../jscript/codes.js">
|
||||
</script>
|
||||
|
||||
<basefont size="3"> <a name="pthread_create"></a> <a name="tag_03_525"></a><!-- pthread_create -->
|
||||
<!--header start-->
|
||||
<center><font size="2">The Open Group Base Specifications Issue 6<br>
|
||||
IEEE Std 1003.1-2001<br>
|
||||
Copyright © 2001 The IEEE and The Open Group, All Rights reserved.</font></center>
|
||||
|
||||
<!--header end-->
|
||||
<hr size="2" noshade>
|
||||
<h4><a name="tag_03_525_01"></a>NAME</h4>
|
||||
|
||||
<blockquote>pthread_create - thread creation</blockquote>
|
||||
|
||||
<h4><a name="tag_03_525_02"></a>SYNOPSIS</h4>
|
||||
|
||||
<blockquote class="synopsis">
|
||||
<div class="box"><code><tt><sup>[<a href="javascript:open_code('THR')">THR</a>]</sup> <img src="../images/opt-start.gif" alt=
|
||||
"[Option Start]" border="0"> #include <<a href="../basedefs/pthread.h.html">pthread.h</a>><br>
|
||||
<br>
|
||||
int pthread_create(pthread_t *restrict</tt> <i>thread</i><tt>,<br>
|
||||
const pthread_attr_t *restrict</tt> <i>attr</i><tt>,<br>
|
||||
void *(*</tt><i>start_routine</i><tt>)(void*), void *restrict</tt> <i>arg</i><tt>); <img src=
|
||||
"../images/opt-end.gif" alt="[Option End]" border="0"></tt></code></div>
|
||||
|
||||
<tt><br>
|
||||
</tt></blockquote>
|
||||
|
||||
<h4><a name="tag_03_525_03"></a>DESCRIPTION</h4>
|
||||
|
||||
<blockquote>
|
||||
<p>The <i>pthread_create</i>() function shall create a new thread, with attributes specified by <i>attr</i>, within a process. If
|
||||
<i>attr</i> is NULL, the default attributes shall be used. If the attributes specified by <i>attr</i> are modified later, the
|
||||
thread's attributes shall not be affected. Upon successful completion, <i>pthread_create</i>() shall store the ID of the created
|
||||
thread in the location referenced by <i>thread</i>.</p>
|
||||
|
||||
<p>The thread is created executing <i>start_routine</i> with <i>arg</i> as its sole argument. If the <i>start_routine</i> returns,
|
||||
the effect shall be as if there was an implicit call to <a href="../functions/pthread_exit.html"><i>pthread_exit</i>()</a> using
|
||||
the return value of <i>start_routine</i> as the exit status. Note that the thread in which <i>main</i>() was originally invoked
|
||||
differs from this. When it returns from <i>main</i>(), the effect shall be as if there was an implicit call to <a href=
|
||||
"../functions/exit.html"><i>exit</i>()</a> using the return value of <i>main</i>() as the exit status.</p>
|
||||
|
||||
<p>The signal state of the new thread shall be initialized as follows:</p>
|
||||
|
||||
<ul>
|
||||
<li>
|
||||
<p>The signal mask shall be inherited from the creating thread.</p>
|
||||
</li>
|
||||
|
||||
<li>
|
||||
<p>The set of signals pending for the new thread shall be empty.</p>
|
||||
</li>
|
||||
</ul>
|
||||
|
||||
<p>The floating-point environment shall be inherited from the creating thread.</p>
|
||||
|
||||
<p>If <i>pthread_create</i>() fails, no new thread is created and the contents of the location referenced by <i>thread</i> are
|
||||
undefined.</p>
|
||||
|
||||
<p><sup>[<a href="javascript:open_code('TCT')">TCT</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
|
||||
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. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></p>
|
||||
</blockquote>
|
||||
|
||||
<h4><a name="tag_03_525_04"></a>RETURN VALUE</h4>
|
||||
|
||||
<blockquote>
|
||||
<p>If successful, the <i>pthread_create</i>() function shall return zero; otherwise, an error number shall be returned to indicate
|
||||
the error.</p>
|
||||
</blockquote>
|
||||
|
||||
<h4><a name="tag_03_525_05"></a>ERRORS</h4>
|
||||
|
||||
<blockquote>
|
||||
<p>The <i>pthread_create</i>() function shall fail if:</p>
|
||||
|
||||
<dl compact>
|
||||
<dt>[EAGAIN]</dt>
|
||||
|
||||
<dd>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.</dd>
|
||||
|
||||
<dt>[EINVAL]</dt>
|
||||
|
||||
<dd>The value specified by <i>attr</i> is invalid.</dd>
|
||||
|
||||
<dt>[EPERM]</dt>
|
||||
|
||||
<dd>The caller does not have appropriate permission to set the required scheduling parameters or scheduling policy.</dd>
|
||||
</dl>
|
||||
|
||||
<p>The <i>pthread_create</i>() function shall not return an error code of [EINTR].</p>
|
||||
</blockquote>
|
||||
|
||||
<hr>
|
||||
<div class="box"><em>The following sections are informative.</em></div>
|
||||
|
||||
<h4><a name="tag_03_525_06"></a>EXAMPLES</h4>
|
||||
|
||||
<blockquote>
|
||||
<p>None.</p>
|
||||
</blockquote>
|
||||
|
||||
<h4><a name="tag_03_525_07"></a>APPLICATION USAGE</h4>
|
||||
|
||||
<blockquote>
|
||||
<p>None.</p>
|
||||
</blockquote>
|
||||
|
||||
<h4><a name="tag_03_525_08"></a>RATIONALE</h4>
|
||||
|
||||
<blockquote>
|
||||
<p>A suggested alternative to <i>pthread_create</i>() 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".</p>
|
||||
|
||||
<p>Splitting the operation was rejected by the standard developers for many reasons:</p>
|
||||
|
||||
<ul>
|
||||
<li>
|
||||
<p>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.</p>
|
||||
</li>
|
||||
|
||||
<li>
|
||||
<p>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.</p>
|
||||
</li>
|
||||
|
||||
<li>
|
||||
<p>For those applications that require such behavior, it is possible to simulate the two separate steps with the facilities that
|
||||
are currently provided. The <i>start_routine</i>() can synchronize by waiting on a condition variable that is signaled by the start
|
||||
operation.</p>
|
||||
</li>
|
||||
</ul>
|
||||
|
||||
<p>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 <i>start_routine</i>() 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.</p>
|
||||
|
||||
<p>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:</p>
|
||||
|
||||
<ul>
|
||||
<li>
|
||||
<p>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.</p>
|
||||
</li>
|
||||
|
||||
<li>
|
||||
<p>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.</p>
|
||||
</li>
|
||||
|
||||
<li>
|
||||
<p>The ability for applications to segregate threads by class would be lost.</p>
|
||||
</li>
|
||||
</ul>
|
||||
|
||||
<p>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:</p>
|
||||
|
||||
<ul>
|
||||
<li>
|
||||
<p>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.</p>
|
||||
</li>
|
||||
|
||||
<li>
|
||||
<p>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.</p>
|
||||
</li>
|
||||
</ul>
|
||||
</blockquote>
|
||||
|
||||
<h4><a name="tag_03_525_09"></a>FUTURE DIRECTIONS</h4>
|
||||
|
||||
<blockquote>
|
||||
<p>None.</p>
|
||||
</blockquote>
|
||||
|
||||
<h4><a name="tag_03_525_10"></a>SEE ALSO</h4>
|
||||
|
||||
<blockquote>
|
||||
<p><a href="fork.html"><i>fork</i>()</a> , <a href="pthread_exit.html"><i>pthread_exit</i>()</a> , <a href=
|
||||
"pthread_join.html"><i>pthread_join</i>()</a> , the Base Definitions volume of IEEE Std 1003.1-2001, <a href=
|
||||
"../basedefs/pthread.h.html"><i><pthread.h></i></a></p>
|
||||
</blockquote>
|
||||
|
||||
<h4><a name="tag_03_525_11"></a>CHANGE HISTORY</h4>
|
||||
|
||||
<blockquote>
|
||||
<p>First released in Issue 5. Included for alignment with the POSIX Threads Extension.</p>
|
||||
</blockquote>
|
||||
|
||||
<h4><a name="tag_03_525_12"></a>Issue 6</h4>
|
||||
|
||||
<blockquote>
|
||||
<p>The <i>pthread_create</i>() function is marked as part of the Threads option.</p>
|
||||
|
||||
<p>The following new requirements on POSIX implementations derive from alignment with the Single UNIX Specification:</p>
|
||||
|
||||
<ul>
|
||||
<li>
|
||||
<p>The [EPERM] mandatory error condition is added.</p>
|
||||
</li>
|
||||
</ul>
|
||||
|
||||
<p>The thread CPU-time clock semantics are added for alignment with IEEE Std 1003.1d-1999.</p>
|
||||
|
||||
<p>The <b>restrict</b> keyword is added to the <i>pthread_create</i>() prototype for alignment with the ISO/IEC 9899:1999
|
||||
standard.</p>
|
||||
|
||||
<p>The DESCRIPTION is updated to make it explicit that the floating-point environment is inherited from the creating thread.</p>
|
||||
</blockquote>
|
||||
|
||||
<div class="box"><em>End of informative text.</em></div>
|
||||
|
||||
<hr>
|
||||
<hr size="2" noshade>
|
||||
<center><font size="2"><!--footer start-->
|
||||
UNIX ® is a registered Trademark of The Open Group.<br>
|
||||
POSIX ® is a registered Trademark of The IEEE.<br>
|
||||
[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href=
|
||||
"../utilities/contents.html">XCU</a> | <a href="../functions/contents.html">XSH</a> | <a href="../xrat/contents.html">XRAT</a>
|
||||
]</font></center>
|
||||
|
||||
<!--footer end-->
|
||||
<hr size="2" noshade>
|
||||
</body>
|
||||
</html>
|
||||
|
||||
Reference in New Issue
Block a user