SunOS man pages : pthread_create (3)
Threads Library Functions pthread_create(3THR)
NAME
pthread_create - create a thread
SYNOPSIS
cc -mt [ flag... ] file...- lpthread [ library... ]
#include <pthread.h>
int pthread_create(pthread_t *thread, const pthread_attr_t
*attr, void *(*start_routine, void*),void *arg);
DESCRIPTION
The pthread_create() function is used to create a new
thread, with attributes specified by attr, within a process.
If attr is NULL, the default attributes are used. (See
pthread_attr_init(3THR)). If the attributes specified by
attr are modified later, the thread's attributes are not
affected. Upon successful completion, pthread_create()
stores the ID of the created thread in the location refer-
enced by thread.
The thread is created executing start_routine with arg as
its sole argument. If the start_routine returns, the effect
is as if there was an implicit call to pthread_exit() using
the return value of start_routine as the exit status. Note
that the thread in which main() was originally invoked
differs from this. When it returns from main(), the effect
is as if there was an implicit call to exit() using the
return value of main() as the exit status.
The signal state of the new thread is initialised as fol-
lows:
o The signal mask is inherited from the creating thread.
o The set of signals pending for the new thread is
empty.
Default thread creation:
pthread_t tid;
void *start_func(void *), *arg;
pthread_create(&tid, NULL, start_func, arg);
This would have the same effect as:
pthread_attr_t attr;
pthread_attr_init(&attr); /* initialize attr with default attributes */
pthread_create(&tid, &attr, start_func, arg);
SunOS 5.8 Last change: 15 May 1998 1
Threads Library Functions pthread_create(3THR)
User-defined thread creation: To create a thread that is
scheduled on a system-wide basis, use:
pthread_attr_init(&attr); /* initialize attr with default attributes */
pthread_attr_setscope(&attr, PTHREAD_SCOPE_SYSTEM); /* system-wide contention */
pthread_create(&tid, &attr, start_func, arg);
To customize the attributes for POSIX threads, see
pthread_attr_init(3THR).
A new thread created with pthread_create() uses the stack
specified by the stackaddr attribute, and the stack contin-
ues for the number of bytes specified by the stacksize
attribute. By default, the stack size is 1 megabyte for 32-
bit processes and 2 megabyte for 64-bit processes (see
pthread_attr_setstacksize(3THR)). If the default is used for
both the stackaddr and stacksize attributes,
pthread_create() creates a stack for the new thread with at
least 1 megabyte for 32-bit processes and 2 megabyte for
64-bit processes. (For customizing stack sizes, see NOTES).
If pthread_create() fails, no new thread is created and the
contents of the location referenced by thread are undefined.
RETURN VALUES
If successful, the pthread_create() function returns 0.
Otherwise, an error number is returned to indicate the
error.
ERRORS
The pthread_create() function will fail if:
ENOMEM
The system lacked the necessary resources to create
another thread.
EINVAL
The value specified by attr is invalid.
EPERM The caller does not have appropriate permission to set
the required scheduling parameters or scheduling pol-
icy.
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
SunOS 5.8 Last change: 15 May 1998 2
Threads Library Functions pthread_create(3THR)
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 pro-
cess 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);
}
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 */
SunOS 5.8 Last change: 15 May 1998 3
Threads Library Functions pthread_create(3THR)
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);
}
Example 2: If main() had not waited for the completion of
the other threads (using pthread_join(3THR) or
thr_join(3THR)), it would have continued to process con-
currently until it reached the end of its routine and the
entire process would have exited prematurely (see exit(2)).
ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| MT-Level | MT-Safe |
|_____________________________|_____________________________|
SEE ALSO
fork(2), sysconf(3C), pthread_attr_init(3THR),
pthread_cancel(3THR), pthread_exit(3THR),
pthread_join(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.
pthread_join(3THR), on the other hand, must specify the ter-
minating thread (IDs) for which it will wait.
A user-specified stack size must be greater than the value
PTHREAD_STACK_MIN. 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.
SunOS 5.8 Last change: 15 May 1998 4
Threads Library Functions pthread_create(3THR)
It is usually very difficult to determine the runtime stack
requirements for a thread. PTHREAD_STACK_MIN specifies how
much stack storage is required to execute a NULL start_func.
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 (as 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: 15 May 1998 5
|
 |
|
|
