int
pthread_create (
pthread_t *thread,
const pthread_attr_t *attr,
void * (*start_routine) (void *),
void *arg);
thread
Location for thread object to be created.attr
Thread attributes object that defines the characteristics of the thread being created. If you specify NULL, default attributes are used.start_routine
Function executed as the new thread's start routine.arg
Address value copied and passed to the thread's start routine.
This routine creates 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.Return Values If an error condition occurs, no thread is created, the contents of thread are undefined, and this routine returns an integer value indicating the type of error. Possible return values are as follows:Successful execution of this routine includes the following actions:
- DECthreads creates a thread object to describe and control the thread. The thread object includes a thread environment block (TEB) that programs can use, with care. (See the <sys/types.h> header file on DIGITAL UNIX, or the pthread.h header file on other DECthreads platforms.)
- The thread argument receives an identifier for the new thread.
- An executable thread is created with attributes specified by the attr argument (or with default attributes if NULL is specified).
Thread Creation
DECthreads creates a thread in the ready state and prepares the thread to begin executing its start routine, the function passed to pthread_create() as the start_routine argument. Depending on the presence of other threads and their scheduling and priority attributes, the new thread might start executing immediately. The new thread can also preempt its creator, depending on the two threads' respective scheduling and priority attributes. The caller of pthread_create() can synchronize with the new thread using the pthread_join() routine or using any mutually agreed upon mutexes or condition variables.
For the duration of the new thread's existence, DECthreads maintains and manages the thread object and other thread state overhead. A thread exists until it is both terminated and detached. A thread is detached when created if the detachstate attribute of its thread object is set to PTHREAD_CREATE_DETACHED. It is also detached after any thread returns successfully from calling pthread_detach() or pthread_join() for the thread. Termination is explained in the next section (see Thread Termination).
DECthreads assigns each new thread a thread identifier, which DECthreads writes into the address specified as the pthread_create() routine's thread argument. DECthreads writes the new thread's thread identifier before the new thread executes.
By default, the new thread's scheduling policy and priority are inherited from the creating thread---that is, by default, the pthread_create() routine ignores the scheduling policy and priority set in the specified thread attributes object. Thus, to create a thread that is subject to the scheduling policy and priority set in the specified thread attributes object, before calling pthread_create() your program must use the pthread_attr_setinheritsched() routine to set the inherit thread attributes object's scheduling attribute to PTHREAD_EXPLICIT_SCHED.
On DIGITAL UNIX, the signal state of the new thread is initialized as follows:
- The signal mask is inherited from the creating thread.
- The set of signals pending for the new thread is empty.
If pthread_create() fails, no new thread is created, and the contents of the location referenced by thread are undefined.
Thread Termination
A thread terminates when one of the following events occurs:
- The thread returns from its start routine.
- The thread calls the pthread_exit() routine.
- The thread is canceled.
When a thread terminates, DECthreads performs these actions:
- DECthreads writes a return value (if one is available) into the terminated thread's thread object, as follows:
- If the thread has been canceled, DECthreads writes the value PTHREAD_CANCELED into the thread's thread object.
- If the thread terminated by returning from its start routine, DECthreads copies the return value from the start routine (if one is available) into the thread's thread object. Alternatively, if the thread explictly called pthread_exit(), DECthreads stores the value received in the value_ptr argument (from pthread_exit()) into the thread's thread object.
Another thread can obtain this return value by joining with the terminated thread (using pthread_join()). See Section 2.3.5 for a description of joining with a thread.
Note
If the thread terminated by returning from its start routine normally and the start routine does not provide a return value, the results obtained by joining with that thread are unpredictable.
- If the termination results from a cancelation request or a call to pthread_exit(), DECthreads calls, in turn, each cleanup handler that this thread declared (using pthread_cleanup_push()) and that is not yet removed (using pthread_cleanup_pop()). (DECthreads also transfers control to any appropriate CATCH, CATCH_ALL, or FINALLY blocks , as described in Chapter 5 .)
DECthreads calls the terminated thread's most recently pushed cleanup handler first. See Section 2.3.3.1 for more information about cleanup handlers.
For C++ programmers: At normal exit from a thread, your program will call the appropriate destructor functions, just as if an exception had been raised.- To exit the terminated thread due to a call to pthread_exit(), DECthreads raises the pthread_exit_e exception. To exit the terminated thread due to cancelation, DECthreads raises the pthread_cancel_e exception.
Your program can use the DECthreads exception package to operate on the generated exception. (In particular, note that the practice of using CATCH handlers in place of pthread_cleanup_push() is not portable.) Chapter 5 describes the DECthreads exception package.- For each of the terminated thread's thread-specific data keys that has a non-NULL value:
- DECthreads sets the thread's value for the corresponding key to NULL.
- In turn, DECthreads calls each thread-specific data destructor function in this multithreaded process's list of destructors.
DECthreads repeats this step until all thread-specific data values in the thread are NULL, or for up to a number of iterations equal to PTHREAD_DESTRUCTOR_ITERATIONS. This destroys all thread-specific data associated with the terminated thread. See Section 2.5 for more information about thread-specific data.- DECthreads awakens the thread (if there is one) that is currently waiting to join with the terminated thread. That is, DECthreads awakens the thread that is waiting in a call to pthread_join().
- If the thread is already detached, DECthreads destroys its thread object. Otherwise, the thread continues to exist until detached or joined with. Section 2.3.4 describes detaching and destroying a thread.
| Return | Description |
|---|---|
| 0 | Successful completion. |
| [EAGAIN] | The system lacks the necessary resources to create another thread, or the system-imposed limit on the total number of threads under execution by a single user is exceeded. |
| [EINVAL] | The value specified by attr is invalid. |
| [ENOMEM] | Insufficient memory exists to create a thread. |
| [EPERM] | The caller does not have the appropriate permission to create a thread with the specified attributes. |
Delays a thread's execution.
C Binding #include <pthread.h>pthread_delay_np(
interval );
Argument Data Type Access interval struct timespec read
int
pthread_delay_np (
const struct timespec *interval);
interval
Number of seconds and nanoseconds to delay execution. The value specified for each must be greater than or equal to zero.
This routine causes a thread to delay execution for a specific interval of time. This interval ends at the current time plus the specified interval. The routine will not return before the end of the interval is reached, but may return an arbitrary amount of time after the end of the interval is reached. This can be due to system load, thread priorities, and system timer granularity.Return Values If an error condition occurs, this routine returns an integer value indicating the type of error. Possible return values are as follows:Specifying an interval of zero (0) seconds and zero (0) nanoseconds is allowed and can be used to force the thread to give up the processor or to deliver a pending cancelation request.
The timespec structure contains the following two fields:
- tv_sec is an integral number of seconds.
- tv_nsec is an integral number of nanoseconds.
| Return | Description |
|---|---|
| 0 | Successful completion. |
| [EINVAL] | The value specified by interval is invalid. |
Marks a thread object for deletion.
C Binding #include <pthread.h>pthread_detach(
thread );
Argument Data Type Access thread opaque pthread_t read
int
pthread_detach (
pthread_t thread);
thread
Thread object being marked for deletion.
This routine marks the specified thread object to indicate that storage for the corresponding thread can be reclaimed when the thread terminates. This includes storage for the thread argument's return value, as well as the thread object. If thread has not terminated when this routine is called, this routine does not cause it to terminate.Return Values If an error condition occurs, this routine returns an integer indicating the type of error. Possible return values are as follows:When a thread object is no longer referenced, call this routine.
The results of this routine are unpredictable if the value of thread refers to a thread object that does not exist.
A thread can be created already detached by setting its thread object's detachstate attribute.
The pthread_join() routine also detaches the target thread after pthread_join() returns successfully.
| Return | Description |
|---|---|
| 0 | Successful completion. |
| [EINVAL] | The value specified by thread does not refer to a joinable thread. |
| [ESRCH] | The value specified by thread cannot be found. |
Compares one thread identifier to another thread identifier.
C Binding #include <pthread.h>pthread_equal(
t1 ,
t2 );
Argument Data Type Access t1 opaque pthread_t read t2 opaque pthread_t read
int
pthread_equal (
pthread_t t1,
pthread_t t2);
t1
The first thread identifier to be compared.t2
The second thread identifier to be compared.
This routine compares one thread identifier to another thread identifier.Return Values Possible return values are as follows:If either t1 or t2 are not valid thread identifiers, this routine's behavior is undefined.
| Return | Description |
|---|---|
| 0 | Values of t1 and t2 do not designate the same object. |
| Non-zero | Values of t1 and t2 designate the same object. |
(Macro) Obtains a system-defined error status from a DECthreads status exception object.
C Binding #include <pthread_exception.h>pthread_exc_get_status_np(
exception ,
code );
Argument Data Type Access exception EXCEPTION read code unsigned long write
int
pthread_exc_get_status_np (
EXCEPTION *exception,
unsigned long *code);
exception
DECthreads status exception object whose status code is obtained.code
Receives the system-specific status code associated with the specified DECthreads status exception object.
This routine obtains and returns the system-specific status value from the DECthreads status exception object specified in the exception argument. This value must have already been associated with the exception object using the pthread_exc_set_status_np() routine.Return Values If an error condition occurs, this routine returns an integer value indicating the type of error. If the routine's exception object argument is a DECthreads status exception, it sets the code argument and returns zero (0). Possible return values are as follows:In a program that uses DECthreads status exceptions, use this routine within a CATCH, CATCH_ALL, or FINALLY code block to obtain the status code value associated with a caught exception. Note that any exception objects set to the same status value are considered equivalent by DECthreads.
| Return | Description |
|---|---|
| 0 | Successful completion. |
| [EINVAL] | The exception argument is not a valid DECthreads status exception object. |
(Macro) Determines whether two DECthreads exception objects are identical.
C Binding #include <pthread_exception.h>pthread_exc_matches_np(
exception1 ,
exception2 );
Argument Data Type Access exception1 EXCEPTION read exception2 EXCEPTION read
int
pthread_exc_matches_np (
EXCEPTION *exception1,
EXCEPTION *exception2);
exception1
DECthreads exception object.exception2
DECthreads exception object.
This routine compares two DECthreads exception objects, taking into consideration whether each is an address exception or status exception.Return Values The C language value TRUE if the exception objects are identical, or the C language value FALSE if not.This routine returns either the C language value TRUE or the C language value FALSE, indicating whether the two DECthreads exception objects specified in the arguments exception1 and exception2 are identical.
Produces a message that reports what a specified DECthreads status exception object represents.
C Binding #include <pthread_exception.h>pthread_exc_report_np(
exception );
Argument Data Type Access exception EXCEPTION read
void
pthread_exc_report_np (
EXCEPTION *exception);
exception
DECthreads exception object that has been set with a status value.
This routine produces a text message on the stderr device (Digital UNIX and Windows NT systems) or SYS$ERROR device (OpenVMS systems) that describes the exception whose exception object is specified in the exception argument.Return Values NoneIn a program that uses DECthreads status exceptions, use this routine within a CATCH, CATCH_ALL, or FINALLY code block to obtain the status code value associated with a caught exception. Note that any exception objects set to the same status value are considered equivalent by DECthreads.
(Macro) Imports a system-defined error status into a DECthreads address exception object.
C Binding #include <pthread_exception.h>pthread_exc_set_status_np(
exception ,
code );
Argument Data Type Access exception EXCEPTION write code unsigned long read
void
pthread_exc_set_status_np (
EXCEPTION *exception,
unsigned long code);
exception
DECthreads address exception object into which the specified status code is imported.code
System-specific status code to be imported.
This routine associates a system-specific status value with the specified DECthreads address exception object. This transforms the address exception object into a DECthreads status exception object.Return Values NoneThe exception argument must already have been initialized with the DECthreads exception package's EXCEPTION_INIT macro.
Use this routine to associate any system-specific status value with the specified DECthreads address exception object. Note that any exception objects set to the same status value are considered equivalent by DECthreads.
Terminates the calling thread.
C Binding #include <pthread.h>pthread_exit(
value _ptr );
Argument Data Type Access value_ptr void * read
void
pthread_exit (
void *value_ptr);
value_ptr
Value copied and returned to the caller of pthread_join(). Note that void* is used as a universal datatype, not as a pointer. DECthreads treats the value_ptr as a value and stores it to be returned by pthread_join().
This routine terminates the calling thread and makes a status value (value_ptr) available to any thread that calls pthread_join() and specifies the terminating thread.Return Values NoneAny cleanup handlers that have been pushed and not yet popped from the stack, are popped in the reverse order that they were pushed and then executed. After all cleanup handlers have been executed, appropriate destructor functions shall be called in an unspecified order if the thread has any thread-specific data. Thread termination does not release any application-visible process resources, including, but not limited to mutexes and file descriptors, nor does it perform any process-level cleanup actions, including, but not limited to calling any atexit() routine that may exist.
An implicit call to pthread_exit() is issued when a thread returns from the start routine that was used to create it. DECthreads writes the function's return value as the return value in the thread's thread object. The process exits when the last running thread calls pthread_exit().
After a thread has terminated, the result of access to local (that is, explicitly or implicitly declared auto) variables of the thread is undefined. So, references to local variables of the existing thread should not be used for the value_ptr argument of the pthread_exit() routine.
Obtains the value of the concurrency level global variable for this process.
C Binding #include <pthread.h>pthread_getconcurrency(
);
int
pthread_getconcurrency (
void);
This routine obtains and returns the value of the "concurrency level" global setting for the calling thread's process. Because DECthreads automatically manages the concurrency of all threads in a multithreaded process, DECthreads ignores this concurrency level value.Return Values This routine always returns the value of this process's concurrency level global variable. If this process has never called the pthread_setconcurrency() routine, this routine returns zero (3).The concurrency level value has no effect on the behavior of a multithreaded program that uses DECthreads. This routine is provided for Single UNIX Specification, Version 2, source code compatibility and has no other effect when called.
The initial concurrency level is zero (0), indicating that DECthreads controls the concurrency level.
The concurrency level can be set using the pthread_setconcurrency() routine.
Obtains the object name from the thread object for an existing thread.
C Binding #include <pthread.h>pthread_getname_np(
thread ,
name ,
len );
Argument Data Type Access thread opaque pthread_thread_t read name char write len opaque size_t read
int
pthread_getname_np (
pthread_thread_t thread,
char *name,
size_t len);
thread
Thread object whose object name is to be obtained.name
Location to store the obtained object name.len
Length in bytes of buffer at the location specified by name.
This routine copies the object name from the thread object specified by the thread argument to the buffer at the location specified by the name argument. Before calling this routine, your program must allocate the buffer indicated by name.Return Values If an error condition occurs, this routine returns an integer value indicating the type of error. Possible return values are as follows:The object name is a C language string and provides an identifier that is meaningful to a person debugging a DECthreads-based multithreaded application. The maximum number of characters in the object name is 31.
If the specified thread object has not been previously set with an object name, this routine copies a C language null string into the buffer at location name.
| Return | Description |
|---|---|
| 0 | Successful completion. |
| [ESRCH] | The thread specified by thread does not exist. |
Obtains the current scheduling policy and scheduling parameters of a thread.
C Binding #include <pthread.h>pthread_getschedparam(
thread ,
policy ,
param );
Argument Data Type Access thread opaque pthread_t read policy integer write param struct sched_param write