pthread_create(3-thr) pthread_create(3-thr)
NAME
pthreadcreate - creates a thread object and thread
SYNOPSIS
#include <pthread.h>
int pthreadcreate(
pthreadt *thread,
pthreadattrt attr,
pthreadstartroutinet startroutine,
pthreadaddrt arg);
PARAMETERS
thread Handle to the thread object created.
attr Thread attributes object that defines the characteris-
tics of the thread being created. If you specify
pthreadattrdefault, default attributes are used.
startroutine Function executed as the new thread's start routine.
arg Address value copied and passed to the thread's start
routine.
DESCRIPTION
The pthreadcreate() routine creates a thread object and a thread. A
thread is a single, sequential flow of control within a program. It is
the active execution of a designated routine, including any nested
routine invocations. A thread object defines and controls the execut-
ing thread.
Creating a Thread
Calling this routine sets into motion the following actions:
- An internal thread object is created to describe the thread.
- The associated executable thread is created with attributes speci-
fied by the attr parameter (or with default attributes if
pthreadattrdefault is specified).
- The thread parameter receives the new thread.
- The startroutine function is called. This may occur before this
routine returns successfully.
Page 1 Reliant UNIX 5.44 Printed 11/98
pthread_create(3-thr) pthread_create(3-thr)
Thread Execution
The thread is created in the ready state and therefore might immedi-
ately begin executing the function specified by the startroutine
parameter. The newly created thread begins running before
pthreadcreate() completes if the new thread follows the SCHEDRR or
SCHEDFIFO scheduling policy or has a priority higher than the creat-
ing thread, or both. Otherwise, the new thread begins running at its
turn, which with sufficient processors might also be before
pthreadcreate() returns.
The startroutine parameter is passed a copy of the arg parameter. The
value of the arg parameter is unspecified.
The thread object exists until the pthreaddetach() routine is called
or the thread terminates, whichever occurs last.
The synchronization between the caller of pthreadcreate() and the
newly created thread is through the use of the pthreadjoin() routine
(or any other mutexes or condition variables they agree to use).
Terminating a Thread
A thread terminates when one of the following events occurs:
- The thread returns from its start routine.
- The thread exits (within a routine) as the result of calling the
pthreadexit() routine.
- The thread is canceled.
When a Thread Terminates
The following actions are performed when a thread terminates:
- If the thread terminates by returning from its start routine or
calling pthreadexit(), the return value is copied into the thread
object. If the start routine returns normally and the start routine
is a procedure that does not return a value, then the result
obtained by pthreadjoin() is unpredictable. If the thread has been
cancelled, a return value of -1 is copied into the thread object.
The return value can be retrieved by other threads by calling the
pthreadjoin() routine.
- A destructor for each thread-specific data point is removed from
the list of destructors for this thread and then is called. This
step destroys all the thread-specific data associated with the
current thread.
- Each cleanup handler that has been declared by
pthreadcleanuppush() and not yet removed by pthreadcleanuppop()
is called. The most recently pushed handler is called first.
Page 2 Reliant UNIX 5.44 Printed 11/98
pthread_create(3-thr) pthread_create(3-thr)
- A flag is set in the thread object indicating that the thread has
terminated. This flag must be set in order for callers of
pthreadjoin() to return from the call.
- A broadcast is made so that all threads currently waiting in a call
to pthreadjoin() can return from the call.
- The thread object is marked to indicate that it is no longer needed
by the thread itself. A check is made to determine if the thread
object is no longer needed by other threads; that is, if
pthreaddetach() has been called. If that routine is called, then
the thread object is deallocated.
RETURN VALUES
Upon successful completion, this routine stores the identifier of the
created thread at thread and returns 0. Otherwise, a value of -1 is
returned and no thread is created, the contents of thread are unde-
fined, and errno may be set to one of the following values:
EAGAIN The system lacks the necessary resources to create another
thread.
ENOMEM Insufficient memory exists to create the thread object. This
is not a temporary condition.
SEE ALSO
pthreadattrcreate(3-thr), pthreadcancel(3-thr),
pthreaddetach(3-thr), pthreadexit(3-thr), pthreadjoin(3-thr).
Page 3 Reliant UNIX 5.44 Printed 11/98