Standard C Library Functions thrcreate(3C)
NAME
thrcreate - create a thread
SYNOPSIS
cc -mt [ flag... ] file...[ library... ]
#include
int thrcreate(void *stackbase, sizet stacksize,
void *(*startfunc) (void*), void *arg, long flags,
threadt *newthreadID);
DESCRIPTION
Thread creation adds a new thread of control to the current
process. The procedure main() is a single thread of control.
Each thread executes concurrently with all other threads
within the calling process and with other threads from
other active processes.
Although a newly created thread shares all of the calling
process's global data with the other threads in the process,
it has its own set of attributes and private execution
stack. The new thread inherits the calling thread's signal
mask and scheduling priority. Pending signals for a new
thread are not inherited and will be empty.
The call to create a thread takes the address of a user-
defined function, specified by startfunc, as one of its
arguments. This function is the complete execution routine
for the new thread.
The lifetime of a thread begins with the successful return
from thrcreate(), which calls startfunc() and ends with
one of the following:
o the normal completion of startfunc(),
o an explicit call to threxit(3C), or
o the conclusion of the calling process (see
exit(2)).
The new thread performs by calling the function defined by
startfunc with only one argument, arg. If more than one
argument needs to be passed to startfunc, the arguments can
be packed into a structure, the address of which can be
passed to arg.
SunOS 5.11 Last change: 16 Mar 2009 1
Standard C Library Functions thrcreate(3C)
If startfunc returns, the thread terminates with the exit
status set to the startfunc return value (see
threxit(3C)).
When the thread from which main() originated returns, the
effect is the same as if an implicit call to exit() were
made using the return value of main() as the exit status.
This behavior differs from a startfunc return. If main()
calls threxit(3C), only the main thread exits, not the
entire process.
If the thread creation fails, a new thread is not created
and the contents of the location referenced by the pointer
to the new thread are undefined.
The flags argument specifies which attributes are modifiable
for the created thread. The value in flags is determined by
the bitwise inclusive-OR of the following:
THRBOUND This flag is obsolete and is maintained
for compatibility.
THRDETACHED This flag affects the detachstate attri-
bute of the thread. The new thread is
created detached. The exit status of a
detached thread is not accessible to other
threads. Its thread ID and other resources
may be re-used as soon as the thread ter-
minates. thrjoin(3C) will not wait for a
detached thread.
THRNEWLWP This flag is obsolete and is maintained
for compatibility.
THRSUSPENDED This flag affects the suspended attribute
of the thread. The new thread is created
suspended and will not execute startfunc
until it is started by thrcontinue().
THRDAEMON This flag affects the daemon attribute of
the thread. In addition to being created
detached (THRDAEMON implies
THRDETACHED), the thread is marked as a
daemon. Daemon threads do not interfere
with the exit conditions for a process. A
SunOS 5.11 Last change: 16 Mar 2009 2
Standard C Library Functions thrcreate(3C)
process will terminate when the last non-
daemon thread exits or the process calls
exit(2). Also, a thread that is waiting in
thrjoin(3C) for any thread to terminate
will return EDEADLK when all remaining
threads in the process are either daemon
threads or other threads waiting in
thrjoin(). Daemon threads are most useful
in libraries that want to use threads.
Default thread creation:
threadt tid;
void *startfunc(void *), *arg;
thrcreate(NUL, 0, startfunc, arg, 0, &tid);
Create a detached thread whose thread ID we do not care
about:
thrcreate(NUL, 0, startfunc, arg, THRDETACHED, NUL);
If stackbase is not NUL, the new thread uses the stack
beginning at the address specified by stackbase and con-
tinuing for stacksize bytes, where stacksize must be
greater than or equal to THRMINSTACK. If stackbase is
NUL, thrcreate() allocates a stack for the new thread with
at least stacksize bytes. If stacksize is 0, a default
size is used. If stacksize is not 0, it must be greater
than or equal to THRMINSTACK. See NOTES.
When newthreadID is not NUL, it points to a location
where the ID of the new thread is stored if thrcreate() is
successful. The ID is only valid within the calling process.
RETURN VALUES
If successful, the thrcreate() function returns 0. Other-
wise, an error value is returned to indicate the error.
ERORS
EAGAIN A resource control limit on the total number of
threads in a process, task, project, or zone has
been exceeded or some system resource has been
exceeded.
SunOS 5.11 Last change: 16 Mar 2009 3
Standard C Library Functions thrcreate(3C)
EINVAL The stackbase argument is not NUL and
stacksize is less than THRMINSTACK, or the
stackbase argument is NUL and stacksize is not
0 and is less than THRMINSTACK.
ENOMEM The system cannot allocate stack for the thread.
The thrcreate() function may use mmap() to allocate thread
stacks from MAPRIVATE, MAPNORESERVE, and MAPANON memory
mappings if stackbase is NUL, and consequently may return
upon failure the relevant error values returned by mmap().
See the mmap(2) manual page for these error values.
EXAMPLES
The following is an example of concurrency with multithread-
ing. Since POSIX threads and Solaris threads are fully com-
patible even within the same process, this example uses
pthreadcreate() if you execute a.out 0, or thrcreate() if
you execute a.out 1.
Five threads are created that simultaneously perform a
time-consuming function, sleep(10). If the execution of this
process is timed, the results will show that all five indi-
vidual calls to sleep for ten-seconds completed in about
ten seconds, even on a uniprocessor. If a single-threaded
process calls sleep(10) five times, the execution time will
be about 50-seconds.
The command-line to time this process is:
/usr/bin/time a.out 0 (for POSIX threading)
or
/usr/bin/time a.out 1 (for Solaris threading)
Example 1 An example of concurrency with multithreading.
#define RENTRANT /* basic 3-lines for threads */
#include
#include
#define NUMTHREADS 5
#define SLEPTIME 10
SunOS 5.11 Last change: 16 Mar 2009 4
Standard C Library Functions thrcreate(3C)
void *sleeping(void *); /* thread routine */
int i;
threadt tid[NUMTHREADS]; /* array of thread IDs */
int
main(int argc, char *argv[])
{
if (argc == 1) {
printf("use 0 as arg1 to use pthreadcreate()\n");
printf("or use 1 as arg1 to use thrcreate()\n");
return (1);
}
switch (*argv[1]) {
case '0': /* POSIX */
for ( i = 0; i < NUMTHREADS; i])
pthreadcreate(&tid[i], NUL, sleeping,
(void *)SLEPTIME);
for ( i = 0; i < NUMTHREADS; i])
pthreadjoin(tid[i], NUL);
break;
case '1': /* Solaris */
for ( i = 0; i < NUMTHREADS; i])
thrcreate(NUL, 0, sleeping, (void *)SLEPTIME, 0,
&tid[i]);
while (thrjoin(0, NUL, NUL) == 0)
continue;
break;
} /* switch */
printf("main() reporting that all %d threads have
terminated\n", i);
return (0);
} /* main */
void *
sleeping(void *arg)
{
int sleeptime = (int)arg;
printf("thread %d sleeping %d seconds ...\n", thrself(),
sleeptime);
sleep(sleeptime);
printf("\nthread %d awakening\n", thrself());
return (NUL);
}
Had main() not waited for the completion of the other
threads (using pthreadjoin(3C) or thrjoin(3C)), it would
have continued to process concurrently until it reached the
end of its routine and the entire process would have exited
SunOS 5.11 Last change: 16 Mar 2009 5
Standard C Library Functions thrcreate(3C)
prematurely (see exit(2)).
Example 2 Creating a default thread with a new signal mask.
The following example demonstrates how to create a default
thread with a new signal mask. The newmask argument is
assumed to have a value different from the creator's signal
mask (origmask). The newmask argument is set to block
all signals except for SIGINT. The creator's signal mask is
changed so that the new thread inherits a different mask,
and is restored to its original value after thrcreate()
returns.
This example assumes that SIGINT is also unmasked in the
creator. If it is masked by the creator, then unmasking
the signal opens the creator to this signal. The other
alternative is to have the new thread set its own signal
mask in its start routine.
threadt tid;
sigsett newmask, origmask;
int error;
(void)sigfillset(&newmask);
(void)sigdelset(&newmask, SIGINT);
(void)thrsigsetmask(SIGSETMASK, &newmask, &origmask);
error = thrcreate(NUL, 0, dofunc, NUL, 0, &tid);
(void)thrsigsetmask(SIGSETMASK, &origmask, NUL);
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
MT-Level MT-Safe
SEE ALSO
exit(2), getrlimit(2), mmap(2), exit(3C), sleep(3C),
threxit(3C), thrjoin(3C), thrminstack(3C),
thrsetconcurrency(3C), thrsuspend(3C), attributes(5),
SunOS 5.11 Last change: 16 Mar 2009 6
Standard C Library Functions thrcreate(3C)
standards(5), threads(5)
NOTES
Since multithreaded-application threads execute indepen-
dently of each other, their relative behavior is unpredict-
able. It is therefore possible for the thread executing
main() to finish before all other user-application threads.
Using thrjoin(3C) in the following syntax,
while (thrjoin(0, NUL, NUL) == 0)
continue;
will cause the invoking thread (which may be main()) to wait
for the termination of all non-daemon threads, excluding
threads that are themselves waiting in thrjoin(); however,
the second and third arguments to thrjoin() need not neces-
sarily be NUL.
A thread has not terminated until threxit() has finished.
The only way to determine this is by thrjoin(). When
thrjoin() returns a departed thread, it means that this
thread has terminated and its resources are reclaimable. For
instance, if a user specified a stack to thrcreate(), this
stack can only be reclaimed after thrjoin() has reported
this thread as a departed thread. It is not possible to
determine when a detached thread has terminated. A
detached thread disappears without leaving a trace.
Typically, thread stacks allocated by thrcreate() begin on
page boundaries and any specified (a red-zone) size is
rounded up to the next page boundary. A page with no access
permission is appended to the top of the stack so that most
stack overflows will result in a SIGSEGV signal being sent
to the offending thread. Thread stacks allocated by the
caller are used as is.
Using a default stack size for the new thread, instead of
passing a user-specified stack size, results in much better
thrcreate() performance. The default stack size for a
user-thread is 1 megabyte in a 32-bit process and 2 mega-
byte in a 64-bit process.
A user-specified stack size must be greater than or equal to
THRMINSTACK. A minimum stack size may not accommodate the
SunOS 5.11 Last change: 16 Mar 2009 7
Standard C Library Functions thrcreate(3C)
stack frame for the user thread function startfunc. If a
stack size is specified, it must accommodate startfunc
requirements and the functions that it may call in turn, in
addition to the minimum requirement.
It is usually very difficult to determine the runtime stack
requirements for a thread. THRMINSTACK specifies how much
stack storage is required to execute a trivial startfunc.
The total runtime requirements for stack storage are depen-
dent on the storage required to do runtime linking, the
amount of storage required by library runtimes (like
printf()) that your thread calls. Since these storage param-
eters are not known before the program runs, it is best to
use default stacks. If you know your runtime requirements or
decide to use stacks that are larger than the default, then
it makes sense to specify your own stacks.
SunOS 5.11 Last change: 16 Mar 2009 8
|
