The stack address attribute of a thread attributes object points to the origin of the stack for a new thread.
Note that the value of the stack address attribute of a particular thread attributes object does not necessarily correspond to the actual stack origin of any existing thread in your multithreaded program. Return Values If an error condition occurs, this routine returns an integer value indicating the type of error. Possible return values are as follows:
| Return | Description |
|---|---|
| 0 | Successful completion. |
Obtains the stacksize attribute of the specified thread attributes object.
C Binding #include <pthread.h>pthread_attr_getstacksize(
attr ,
stacksize );
Argument Data Type Access attr opaque pthread_attr_t read stacksize size_t write
int
pthread_attr_getstacksize (
const pthread_attr_t *attr,
size_t *stacksize);
attr
Thread attributes object whose stacksize attribute is obtained.stacksize
Receives the value for the stacksize attribute of the thread attributes object specified by the attr argument.
This routine obtains the stacksize attribute of the thread attributes object specified in the attr argument.Return Values On successful completion, this routine returns a zero (0) and the stacksize value in the location specified in the stacksize argument.
If an error condition occurs, this routine returns an integer value indicating the type of error. Possible return values are as follows:
| Return | Description |
|---|---|
| 0 | Successful completion. |
| EINVAL | The value specified by attr is invalid. |
Initializes a thread attributes object.
C Binding #include <pthread.h>pthread_attr_init(
attr );
Argument Data Type Access attr opaque pthread_attr_t write
int
pthread_attr_init (
pthread_attr_t *attr);
attr
Address of a thread attributes object to be initialized.
This routine initializes the thread attributes object specified by the attr argument with a set of default attribute values. A thread attributes object is used to specify the attributes of one or more threads when they are created. The attributes object created by this routine is used only in calls to the pthread_create() routine.Return Values If an error condition occurs, the thread attributes object cannot be used, and this routine returns an integer value indicating the type of error. Possible return values are as follows:The following routines change individual attributes of an initialized thread attributes object:
- pthread_attr_setdetachstate()
- pthread_attr_setguardsize()
- pthread_attr_setinheritsched()
- pthread_attr_setschedparam()
- pthread_attr_setschedpolicy()
- pthread_attr_setscope()
- pthread_attr_setstackaddr()
- pthread_attr_setstacksize()
The attributes of the thread attributes object are initialized to default values. The default value of each attribute is discussed in the reference description for each routine listed above.
When a thread attributes object is used to create a thread, the object's attribute values determine the characteristics of the new thread. Thus, attributes objects act as additional arguments to thread creation. Changing the attributes of a thread attributes object does not affect any threads that were previously created using that attributes object.
You can use the same thread attributes object in successive calls to pthread_create(), from any thread. (However, you cannot use the same value of the stack address attribute to create multiple threads that might run concurrently; threads cannot share a stack.) If more than one thread might change the attributes in a shared attributes object, your program must use a mutex to protect the integrity of the attributes object's contents.
When you set the scheduling policy or scheduling parameters, or both, in a thread attributes object, you must disable scheduling inheritance if you want the scheduling attributes you set to be used at thread creation. To disable scheduling inheritance, before creating the new thread use the pthread_attr_setinheritsched() routine to specify the value PTHREAD_EXPLICIT_SCHED for the inherit argument.
| Return | Description |
|---|---|
| 0 | Successful completion. |
| [EINVAL] | The value specified by attr is invalid. |
| [ENOMEM] | Insufficient memory exists to initialize the thread attributes object. |
Changes the detachstate attribute in the specified thread attributes object.
C Binding #include <pthread.h>pthread_attr_setdetachstate(
attr ,
detachstate );
Argument Data Type Access attr opaque pthread_attr_t write detachstate integer read
int
pthread_attr_setdetachstate (
pthread_attr_t *attr,
int detachstate);
attr
Thread attributes object to be modified.detachstate
New value for the detachstate attribute. Valid values are as follows:
PTHREAD_CREATE_JOINABLE This is the default value. Threads are created in "undetached" state. PTHREAD_CREATE_DETACHED The created thread is detached immediately, before it begins running.
This routine changes the detachstate attribute in the thread attributes object specified by the attr argument. The detachstate attribute specifies whether the thread created using the specified thread attributes object is created in a detached state or not. A value of PTHREAD_CREATE_JOINABLE indicates the thread is not detached, and a value of THREAD_CREATE_DETACHED indicates the thread is detached. PTHREAD_CREATE_JOINABLE is the default value.Return Values If an error condition occurs, this routine returns an integer value indicating the type of error. Possible return values are as follows:Your program cannot use the thread handle (the value of type pthread_t returned by the pthread_create() routine) of a detached thread because the thread might terminate asynchronously, and a detached thread ID is not valid after termination. In particular, it is an error to attempt to detach or join with a detached thread.
When a thread that has not been detached completes execution, DECthreads retains the state of that thread to allow another thread to join with it. If the thread is detached before it completes execution, DECthreads is free to immediately reclaim the thread's storage and resources. Failing to detach threads that have completed execution can result in wasting resources, so threads should be detached as soon as the program is done with them. If there is no need to use the thread's handle after creation, create the thread initially detached.
| Return | Description |
|---|---|
| 0 | Successful completion. |
| [EINVAL] | The value specified by the detachstate argument is invalid. |
Changes the guardsize attribute of the specified thread attributes object.
C Binding #include <pthread.h>pthread_attr_setguardsize(
attr ,
guardsize );
Argument Data Type Access attr opaque pthread_attr_t write guardsize size_t read
int
pthread_attr_setguardsize (
pthread_attr_t *attr,
size_t guardsize);
attr
Address of the thread attributes object whose guardsize attribute is to be modified.guardsize
New value for the guardsize attribute of the thread attributes object specified by attr.
This routine uses the value specified in the guardsize argument to set the guardsize attribute of the thread attributes object specified in the attr argument.Return Values If an error condition occurs, this routine returns an integer value indicating the type of error. Possible return values are as follows:When creating a thread, use a thread attributes object to specify nondefault values for thread attributes. The guardsize attribute of a thread attributes object specifies the minimum size (in bytes) of the guard area for the stack of a new thread.
A guard area can help a multithreaded program detect overflow of a thread's stack. A guard area is a region of no-access memory that DECthreads allocates at the overflow end of the thread's stack. When any thread attempts to access a memory location within this region, a memory addressing violation occurs.
A new thread can be created with a default guardsize attribute value. This value is platform dependent, but will always be at least one "hardware protection unit" (that is, at least one page). For more information, see this guide's platform-specific appendixes.
After this routine is called, due to platform-specific factors DECthreads might reserve a larger guard area for the new thread than was specified in the guardsize argument. See this guide's platform-specific appendixes for more information.
DECthreads allows your program to specify the size of a thread stack's guard area for two reasons:
- When a thread allocates large data structures on its stack, a guard area with a size greater than the default size might be required to detect stack overflow.
- Overflow protection of a thread's stack can potentially waste system resources, such as for an application that creates a large number of threads that will never overflow their stacks. Your multithreaded program can conserve system resources by "turning off" a thread's stack guard area---that is, by specifying a guardsize attribute of zero.
If a thread is created using a thread attributes object whose stackaddr attribute is set (using the pthread_attr_setstackaddr() routine), this routine ignores the object's guardsize attribute and provides no thread stack guard area for the new thread.
| Return | Description |
|---|---|
| 0 | Successful completion. |
| [EINVAL] | The argument attr is invalid, or the argument guardsize contains an invalid value. |
Changes the guardsize attribute of the specified thread attributes object.
C Binding #include <pthread.h>pthread_attr_setguardsize_np(
attr ,
guardsize );
Argument Data Type Access attr opaque pthread_attr_t write guardsize size_t read
int
pthread_attr_setguardsize_np (
pthread_attr_t *attr,
size_t guardsize);
attr
Address of the thread attributes object whose guardsize attribute is to be modified.guardsize
New value for the guardsize attribute of the thread attributes object specified by attr.
This routine uses the value specified in the guardsize argument to set the guardsize attribute of the thread attributes object specified in the attr argument.Return Values If an error condition occurs, this routine returns an integer value indicating the type of error. Possible return values are as follows:When creating a thread, use a thread attributes object to specify nondefault values for thread attributes. The guardsize attribute of a thread attributes object specifies the minimum size (in bytes) of the guard area for the stack of a new thread.
A guard area can help a multithreaded program detect overflow of a thread's stack. A guard area is a region of no-access memory that DECthreads allocates at the overflow end of the thread's stack. When any thread attempts to access a memory location within this region, a memory addressing violation occurs.
A new thread can be created with a default guardsize attribute value. This value is platform dependent, but will always be at least one "hardware protection unit" (that is, at least one page). For more information, see this guide's platform-specific appendixes.
After this routine is called, due to platform-specific factors DECthreads might reserve a larger guard area for the new thread than was specified in the guardsize argument. See this guide's platform-specific appendixes for more information.
DECthreads allows your program to specify the size of a thread stack's guard area for two reasons:
- When a thread allocates large data structures on its stack, a guard area with a size greater than the default size might be required to detect stack overflow.
- Overflow protection of a thread's stack can potentially waste system resources, such as for an application that creates a large number of threads that will never overflow their stacks. Your multithreaded program can conserve system resources by "turning off" a thread's stack guard area---that is, by specifying a guardsize attribute of zero.
If a thread is created using a thread attributes object whose stackaddr attribute is set (using the pthread_attr_setstackaddr() routine), this routine ignores the object's guardsize attribute and provides no thread stack guard area for the new thread.
Note
This routine has been superseded by the pthread_attr_setguardsize() routine, as specified by the Single UNIX Specification, Version 2.
| Return | Description |
|---|---|
| 0 | Successful completion. |
| [EINVAL] | The argument attr is invalid, or the argument guardsize contains an invalid value. |
Changes the inherit scheduling attribute of the specified thread attributes object.
C Binding #include <pthread.h>pthread_attr_setinheritsched(
attr ,
inheritsched );
Argument Data Type Access attr opaque pthread_attr_t write inheritsched integer read
int
pthread_attr_setinheritsched (
pthread_attr_t *attr,
int inheritsched);
attr
Thread attributes object whose inherit scheduling attribute is to be modified.inheritsched
New value for the inherit scheduling attribute. Valid values are as follows:
PTHREAD_INHERIT_SCHED The created thread inherits the scheduling policy and associated scheduling attributes of the thread calling pthread_create(). Any scheduling attributes in the attributes object specified by the pthread_create() attr argument are ignored during thread creation. This is the default value. PTHREAD_EXPLICIT_SCHED The scheduling policy and associated scheduling attributes of the created thread are set to the corresponding values from the attribute object specified by the pthread_create() attr argument.
This routine changes the inherit scheduling attribute of the thread attributes object specified by the attr argument. The inherit scheduling attribute specifies whether a thread created using the specified attributes object inherits the scheduling attributes of the creating thread, or uses the scheduling attributes stored in the attributes object specified by the pthread_create() attr argument.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 first thread in an application has a scheduling policy of SCHED_OTHER. See the pthread_attr_setschedparam() and pthread_attr_setschedpolicy() routines for more information on valid priority values and valid scheduling policy values, respectively.
Inheriting scheduling attributes (instead of using the scheduling attributes stored in the attributes object) is useful when a thread is creating several helper threads---that is, threads that are intended to work closely with the creating thread to cooperatively solve the same problem. For example, inherited scheduling attributes ensure that helper threads created in a sort routine execute with the same priority as the calling thread.
| Return | Description |
|---|---|
| 0 | Successful completion. |
| [EINVAL] | One or both of the values specified by inherit and attr are invalid. |
| [ENOTSUP] | An attempt was made to set the attribute to an unsupported value. |
Changes the object name attribute in a thread attributes object.
C Binding #include <pthread.h>pthread_attr_setname_np(
attr ,
name ,
mbz );
Argument Data Type Access attr opaque pthread_attr_t write name char read mbz void read
int
pthread_attr_setname_np (
pthread_attr_t *attr,
const char *name,
void *mbz);
attr
Address of the thread attributes object whose object name attribute is to be changed.name
Object name value to copy into the thread attributes object's object name attribute.mbz
(Must be zero) Argument for use by DECthreads.
This routine changes the object name attribute in the thread attributes object specified by the attr argument to the value specified by the name argument. A new thread created using the thread attributes object is initialized with the object name that was set in that attributes object.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.
This routine contrasts with pthread_setname_np(), which changes the object name in the thread object for an existing thread.
| Return | Description |
|---|---|
| 0 | Successful completion. |
| [EINVAL] | The value specified by attr is invalid, or the length in characters of name exceeds 31. |
| [ENOMEM] | Insufficient memory exists to create a copy of the object name string. |
Changes the values of the parameters associated with a scheduling policy of the specified thread attributes object.
C Binding #include <pthread.h>pthread_attr_setschedparam(
attr ,
param );
Argument Data Type Access attr opaque pthread_attr_t write param struct sched_param read
int
pthread_attr_setschedparam (
pthread_attr_t *attr,
const struct sched_param *param);
attr
Thread attributes object for the scheduling policy attribute whose parameters are to be set.param
A structure containing new values for scheduling parameters associated with the scheduling policy attribute of the specified thread attributes object.
Note
DECthreads provides only the sched_priority scheduling parameter. It allows specifying the scheduling priority. See below for information about this scheduling parameter.
This routine sets the scheduling parameters associated with the scheduling policy attribute of the thread attributes object specified by the attr argument.Scheduling Priority
Use the sched_priority field of a sched_param structure to set a thread's execution priority. The effect of the scheduling priority you assign depends on the scheduling policy specified for the attributes object specified by the attr argument.
By default, a created thread inherits the priority of the thread calling pthread_create(). To specify a priority using this routine, scheduling inheritance must be disabled at the time the thread is created. Before calling pthread_create(), call pthread_attr_setinheritsched() and specify the value PTHREAD_EXPLICIT_SCHED for the inherit argument.
An application specifies priority only to express the urgency of executing the thread relative to other threads. Do not use priority to control mutual exclusion when accessing shared data. With a sufficient number of processors present, all ready threads, regardless of priority, execute simultaneously.
Valid values of the sched_priority scheduling parameter depend on the chosen scheduling policy. Use the POSIX routines sched_get_priority_min() or sched_get_priority_max() to determine the low and high limits of each policy.
Previous | Next | Contents