SunOS man pages : thr_create (3)
Threads Library Functions thr_create(3THR)
NAME
thr_create - create a tread
SYNOPSIS
cc - mt [ flag... ] file...[ library... ]
#include <thread.h>
int thr_create(void *stack_base, size_t stack_size, void
*(*start_func) (void*), void *arg, long flags, thread_t
*new_thread_ID);
DESCRIPTION
Thread creation adds a new thread of control to the current
process. The procedure main() is a single thread of con-
trol. Each thread executes simultaneously 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, possibly, 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 start_func, 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 thr_create(), which calls start_func() and ends with
one of the following:
o the normal completion of start_func(),
o the return from an explicit call to thr_exit(3THR), or
o the conclusion of the calling process (see exit(2)).
The new thread performs by calling the function defined by
start_func with only one argument, arg. If more than one
argument needs to be passed to start_func, the arguments can
be packed into a structure, the address of which can be
passed to arg.
If start_func returns, the thread terminates with the exit
status set to the start_func return value (see
thr_exit(3THR)).
SunOS 5.8 Last change: 12 May 1998 1
Threads Library Functions thr_create(3THR)
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 start_func return. If main()
calls thr_exit(3THR), 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:
THR_BOUND
This flag affects the contentionscope attribute of the
thread. The new thread is created permanently bound to
an LWP (that is, it is a bound thread). This thread
will now contend among system-wide resources.
THR_DETACHED
This flag affects the detachstate attribute 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 terminates. thr_join(3THR)
will not wait for a detached thread.
THR_NEW_LWP
This flag affects the concurrency attribute of the
thread. The desired concurrency level for unbound
threads is increased by one. This is similar to incre-
menting concurrency by one by way of
thr_setconcurrency(3THR) Typically, this adds a new
LWP to the pool of LWPs running unbound threads.
THR_SUSPENDED
This flag affects the suspended attribute of the
thread. The new thread is created suspended and will
not execute start_func until it is started by
thr_continue().
THR_DAEMON
This flag affects the daemon attribute of the thread.
The thread is marked as a daemon. The process will
exit when all non-daemon threads exit. thr_join(3THR)
will not wait for a daemon thread. Daemon threads do
not interfere with the exit conditions for a process.
A process will terminate when all regular threads exit
or the process calls exit(). Daemon threads are most
useful in libraries that want to use threads.
SunOS 5.8 Last change: 12 May 1998 2
Threads Library Functions thr_create(3THR)
Default thread creation:
thread_t tid;
void *start_func(void *), *arg;
thr_create(NULL, NULL, start_func, arg, NULL, &tid);
User-defined thread creation (create a thread scheduled on a
system-wide basis, that is, a bound thread):
thr_create(NULL, NULL, start_func, arg, THR_BOUND, &tid);
If both THR_BOUND and THR_NEW_LWP are specified, two LWPs
are created, one for the bound thread and another for the
pool of LWPs running unbound threads.
thr_create(NULL, NULL, start_func, arg, THR_BOUND | THR_NEW_LWP, &tid);
With thr_create(), the new thread uses the stack
beginning at the address specified by stack_base and con-
tinuing for stack_size bytes. The stack_size argument must
be greater than the value returned by thr_min_stack(3THR).
If stack_base is NULL, thr_create() allocates a stack for
the new thread with at least stack_size bytes. If stack_size
is 0, a default size is used. If stack_size is not 0, it
must be greater than the value returned by
thr_min_stack(3THR) See NOTES.
When new_thread_ID is not NULL, it points to a location
where the ID of the new thread is stored if thr_create() is
successful. The ID is only valid within the calling pro-
cess.
RETURN VALUES
If successful, the thr_create() function returns 0. Other-
wise, an error value is returned to indicate the error. If
the application is not linked with the threads library, -1
is returned.
ERRORS
The thr_create() function will fail if:
EAGAIN
The system-imposed limit on the total number of
threads in a process has been exceeded or some system
resource has been exceeded (for example, too many LWPs
were created).
EINVAL
The stack_base argument is not NULL and stack_size is
less than the value returned by thr_min_stack(3THR),
or the stack_base argument is NULLNULL and stack_size
SunOS 5.8 Last change: 12 May 1998 3
Threads Library Functions thr_create(3THR)
is not 0 and is less than the value returned by
thr_min_stack(3THR).
The thr_create() function may use mmap() to allocate thread
stacks from MAP_PRIVATE, MAP_NORESERVE, and MAP_ANON memory
mappings if stack_base is NULL, and consequently may return
upon failure the revelevant error values returned by mmap().
See the mmap(2) manual page for these error values.
EXAMPLES
Example 1: This is an example of concurrency with multi-
threading. Since POSIX threads and Solaris threads are
fully compatible even within the same process, this example
uses pthread_create() if you execute a.out 0, or
thr_create() 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)
/* cc thisfile.c -lthread -lpthread */
#define _REENTRANT /* basic 3-lines for threads */
#include <pthread.h>
#include <thread.h>
#define NUM_THREADS 5
#define SLEEP_TIME 10
void *sleeping(void *); /* thread routine */
int i;
thread_t tid[NUM_THREADS]; /* array of thread IDs */
int
main(int argc, char *argv[])
{
if (argc == 1) {
printf("use 0 as arg1 to use pthread_create()\n");
printf("or use 1 as arg1 to use thr_create()\n");
return (1);
}
SunOS 5.8 Last change: 12 May 1998 4
Threads Library Functions thr_create(3THR)
switch (*argv[1]) {
case '0': /* POSIX */
for ( i = 0; i < NUM_THREADS; i++)
pthread_create(&tid[i], NULL, sleeping,
(void *)SLEEP_TIME);
for ( i = 0; i < NUM_THREADS; i++)
pthread_join(tid[i], NULL);
break;
case '1': /* Solaris */
for ( i = 0; i < NUM_THREADS; i++)
thr_create(NULL, 0, sleeping, (void *)SLEEP_TIME, 0,
&tid[i]);
while (thr_join(NULL, NULL, NULL) == 0)
;
break;
} /* switch */
printf("main() reporting that all %d threads have terminated\n", i);
return (0);
} /* main */
void *
sleeping(void *arg)
{
int sleep_time = (int)arg;
printf("thread %d sleeping %d seconds ...\n", thr_self(), sleep_time);
sleep(sleep_time);
printf("\nthread %d awakening\n", thr_self());
return (NULL);
}
Had main() not waited for the completion of the other
threads (using pthread_join(3THR) or thr_join(3THR)), it
would have continued to process concurrently until it
reached the end of its routine and the entire process would
have exited 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 new_mask argument is
assumed to have a value different from the creator's signal
mask (orig_mask). The new_mask 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 thr_create()
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
SunOS 5.8 Last change: 12 May 1998 5
Threads Library Functions thr_create(3THR)
mask in its start routine.
thread_t tid;
sigset_t new_mask, orig_mask;
int error;
(void)sigfillset(&new_mask);
(void)sigdelset(&new_mask, SIGINT);
(void)thr_sigsetmask(SIG_SETMASK, &new_mask, &orig_mask):
error = thr_create(NULL, 0, do_func, NULL, 0, &tid);
(void)thr_sigsetmask(SIG_SETMASK, &orig_mask, NULL);
ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| MT-Level | MT-Safe |
|_____________________________|_____________________________|
SEE ALSO
_lwp_create(2), exit(2), getrlimit(2), mmap(2), exit(3C),
sleep(3C), thr_min_stack(3THR), thr_setconcurrency(3THR),
thr_suspend(3THR), threads(3THR), attributes(5), standards(5)
NOTES
MT application threads execute independently of each other,
thus their relative behavior is unpredictable. Therefore, it
is possible for the thread executing main() to finish before
all other user application threads.
Using thr_join(3THR) in the following syntax,
while (thr_join(NULL, NULL, NULL) == 0);
will cause the invoking thread (which may be main()) to wait
for the termination of all other undetached and non-daemon
threads; however, the second and third arguments to
thr_join(3THR) need not necessarily be NULL.
A thread has not terminated until thr_exit() has finished.
The only way to determine this is by thr_join(). When
thr_join() 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 thr_create(), this
stack can only be reclaimed after thr_join() has reported
this thread as a departed thread. It is not possible to
determine when a detached thread has terminated. A
SunOS 5.8 Last change: 12 May 1998 6
Threads Library Functions thr_create(3THR)
detached thread disappears without leaving a trace.
Typically, thread stacks allocated by thr_create() 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
thr_create() 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 the value
THR_MIN_STACK. A minimum stack size may not accommodate the
stack frame for the user thread function start_func. If a
stack size is specified, it must accommodate start_func
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. THR_MIN_STACK specifies how much
stack storage is required to execute a NULL start_func. The
total runtime requirements for stack storage are dependent
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 parameters 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.8 Last change: 12 May 1998 7
|
 |
|
|
