 |
Guide to DECthreads
pthread_attr_getschedparam
Obtains the scheduling parameters for an attribute of the specified
thread attributes object.
Syntax
pthread_attr_getschedparam( attr , param );
Argument |
Data Type |
Access |
attr
|
opaque pthread_attr_t
|
read
|
param
|
struct sched_param
|
write
|
C Binding #include <pthread.h> int
pthread_attr_getschedparam (
const pthread_attr_t *attr,
struct sched_param *param);
Arguments
attr
Thread attributes object of the scheduling policy attribute whose
parameters are obtained.
param
Receives the values of scheduling parameters for the scheduling policy
attribute of the attributes object specified by the attr
argument. Refer to the description of the
pthread_attr_setschedparam() routine for valid parameters and
their values.
Description
This routine obtains the scheduling parameters associated with the
scheduling policy attribute of the specified thread 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:
Return |
Description |
0
|
Successful completion.
|
[EINVAL]
|
The value specified by
attr is invalid.
|
Associated Routines
- pthread_attr_init()
- pthread_attr_setschedparam()
- pthread_create()
pthread_attr_getschedpolicy
Obtains the scheduling policy attribute of the specified thread
attributes object.
Syntax
pthread_attr_getschedpolicy( attr , policy );
Argument |
Data Type |
Access |
attr
|
opaque pthread_attr_t
|
read
|
policy
|
integer
|
write
|
C Binding #include <pthread.h> int
pthread_attr_getschedpolicy (
const pthread_attr_t *attr,
int *policy);
Arguments
attr
Thread attributes object whose scheduling policy attribute is obtained.
policy
Receives the value of the scheduling policy attribute. Refer to the
description of the pthread_attr_setschedpolicy() routine for
valid values.
Description
This routine obtains the value of the scheduling policy attribute of
the specified thread attributes object. The scheduling policy attribute
defines the scheduling policy for threads created using the 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:
Return |
Description |
0
|
Successful completion.
|
[EINVAL]
|
The value specified by
attr is invalid.
|
Associated Routines
- pthread_attr_init()
- pthread_attr_setschedpolicy()
- pthread_create()
pthread_attr_getscope
Obtains the contention scope attribute of the specified thread
attributes object.
Syntax
pthread_attr_getscope( attr , scope );
Argument |
Data Type |
Access |
attr
|
opaque pthread_attr_t
|
read
|
scope
|
int
|
write
|
C Binding #include <pthread.h> int
pthread_attr_getscope (
const pthread_attr_t *attr,
int *scope);
Arguments
attr
Address of the thread attributes object whose contention scope
attribute is obtained.
scope
Receives the value of the contention scope attribute of the thread
attributes object specified by attr.
Description
This routine obtains the value of the contention scope attribute of the
thread attributes object specified in the attr argument and
stores it in the location specified by the scope argument. The
specified attributes object must already be initialized at the time
this routine is called.
The contention scope attribute specifies the set of threads with which
a thread must compete for processing resources. The contention scope
attribute specifies whether the new thread competes for processing
resources only with other threads in its own process, called
process contention scope, or with all threads on the
system, called system contention scope.
DECthreads selects at most one thread to execute on each processor at
any point in time. DECthreads resolves the contention based on each
thread's scheduling attributes (for example, priority) and scheduling
policy (for example, round-robin).
A thread created using a thread attributes object whose contention
scope attribute is set to PTHREAD_SCOPE_PROCESS contends for
processing resources with other threads within its own process that
also were created with PTHREAD_SCOPE_PROCESS. It is
unspecified how such threads are scheduled relative to threads in other
processes or threads in the same process that were created with
PTHREAD_SCOPE_SYSTEM contention scope.
A thread created using a thread attributes object whose contention
scope attribute is set to PTHREAD_SCOPE_SYSTEM contends for
processing resources with other threads in any process that also were
created with PTHREAD_SCOPE_SYSTEM.
Note that the value of the contention scope attribute of a particular
thread attributes object does not necessarily correspond to the actual
scheduling contention scope 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.
|
[ENOSYS]
|
This routine is not supported by the implementation.
|
Associated Routines
- pthread_attr_init()
- pthread_attr_setscope()
pthread_attr_getstackaddr
Obtains the stack address attribute of the specified thread attributes
object.
Syntax
pthread_attr_getstackaddr( attr , stackaddr );
Argument |
Data Type |
Access |
attr
|
opaque pthread_attr_t
|
read
|
stackaddr
|
void
|
write
|
C Binding #include <pthread.h> int
pthread_attr_getstackaddr (
const pthread_attr_t *attr,
void **stackaddr);
Arguments
attr
Address of the thread attributes object whose stack address attribute
is obtained.
stackaddr
Receives the value of the stack address attribute of the thread
attributes object specified by attr.
Description
This routine obtains the value of the stack address attribute of the
thread attributes object specified in the attr argument and
stores it in the location specified by the stackaddr argument.
The specified attributes object must already be initialized at the time
this routine is called.
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.
|
Associated Routines
- pthread_attr_getguardsize()
- pthread_attr_getstacksize()
- pthread_attr_init()
- pthread_attr_setguardsize()
- pthread_attr_setstackaddr()
- pthread_attr_setstacksize()
- pthread_create()
pthread_attr_getstacksize
Obtains the stacksize attribute of the specified thread attributes
object.
Syntax
pthread_attr_getstacksize( attr , stacksize );
Argument |
Data Type |
Access |
attr
|
opaque pthread_attr_t
|
read
|
stacksize
|
size_t
|
write
|
C Binding #include <pthread.h> int
pthread_attr_getstacksize (
const pthread_attr_t *attr,
size_t *stacksize);
Arguments
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.
Description
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.
|
Associated Routines
- pthread_attr_init()
- pthread_attr_setstacksize()
- pthread_create()
pthread_attr_init
Initializes a thread attributes object.
Syntax
pthread_attr_init( attr );
Argument |
Data Type |
Access |
attr
|
opaque pthread_attr_t
|
write
|
C Binding #include <pthread.h> int
pthread_attr_init (
pthread_attr_t *attr);
Arguments
attr
Address of a thread attributes object to be initialized.
Description
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.
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 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:
Return |
Description |
0
|
Successful completion.
|
[EINVAL]
|
The value specified by
attr is invalid.
|
[ENOMEM]
|
Insufficient memory exists to initialize the thread attributes object.
|
Associated Routines
- pthread_attr_destroy()
- pthread_attr_setdetachstate()
- pthread_attr_setguardsize()
- pthread_attr_setinheritsched()
- pthread_attr_setschedparam()
- pthread_attr_setschedpolicy()
- pthread_attr_setscope()
- pthread_attr_setstackaddr()
- pthread_attr_setstacksize()
- pthread_create()
pthread_attr_setdetachstate
Changes the detachstate attribute in the specified thread attributes
object.
Syntax
pthread_attr_setdetachstate( attr , detachstate );
Argument |
Data Type |
Access |
attr
|
opaque pthread_attr_t
|
write
|
detachstate
|
integer
|
read
|
C Binding #include <pthread.h> int
pthread_attr_setdetachstate (
pthread_attr_t *attr,
int detachstate);
Arguments
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.
|
Description
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.
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 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.
|
[EINVAL]
|
The value specified by the
detachstate argument is invalid.
|
Associated Routines
- pthread_attr_init()
- pthread_attr_getdetachstate()
- pthread_create()
- pthread_join()
pthread_attr_setguardsize
Changes the guardsize attribute of the specified thread attributes
object.
Syntax
pthread_attr_setguardsize( attr , guardsize );
Argument |
Data Type |
Access |
attr
|
opaque pthread_attr_t
|
write
|
guardsize
|
size_t
|
read
|
C Binding #include <pthread.h> int
pthread_attr_setguardsize (
pthread_attr_t *attr,
size_t guardsize);
Arguments
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.
Description
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.
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 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.
|
[EINVAL]
|
The argument
attr is invalid, or the argument
guardsize contains an invalid value.
|
Associated Routines
- pthread_attr_init()
- pthread_attr_getguardsize()
- pthread_attr_setstacksize()
- pthread_create()
|