Guide to the POSIX Threads Library
pthread_setname_np
Changes the object name in the thread object for an existing thread.
Syntax
pthread_setname_np( thread , name , mbz );
Argument |
Data Type |
Access |
thread
|
opaque pthread_thread_t
|
write
|
name
|
char
|
read
|
mbz
|
void
|
read
|
C Binding #include <pthread.h>
int
pthread_setname_np (
pthread_thread_t thread,
const char *name,
void *mbz);
Arguments
thread
Thread object whose object name is to be changed.
name
Object name value to copy into the thread object.
mbz
Reserved for future use. The value must be zero (0).
Description
This routine changes the object name in the thread object for the
thread specified by the thread argument to the value specified
by the name argument. To set an existing thread's object name,
call this routine after creating the thread. However, with this
approach your program must account for the possibility that the target
thread either has already exited or has been canceled before this
routine is called.
The object name is a C language string and provides an identifier that
is meaningful to a person debugging a multithreaded application. The
maximum number of characters in the object name is 31.
This routine contrasts with
pthread_attr_setname_np()
, which changes the object name attribute in a thread attributes object
that is used to create a 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 length in characters of
name exceeds 31.
|
[ENOMEM]
|
Insufficient memory to create a copy of the object name string.
|
[ESRCH]
|
The thread specified by
thread does not exist.
|
Associated Routines
pthread_attr_getname_np()
pthread_attr_setname_np()
pthread_getname_np()
pthread_setschedparam
Changes a thread's scheduling policy and scheduling parameters.
Syntax
pthread_setschedparam( thread , policy , param );
Argument |
Data Type |
Access |
thread
|
opaque pthread_t
|
read
|
policy
|
integer
|
read
|
param
|
struct sched_param
|
read
|
C Binding #include <pthread.h>
int
pthread_setschedparam (
pthread_t thread,
int policy,
const struct sched_param *param);
Arguments
thread
Thread whose scheduling policy and parameters are to be changed.
policy
New scheduling policy value for the thread specified in
thread. The following are valid values:
SCHED_BG_NP
SCHED_FG_NP
SCHED_FIFO
SCHED_OTHER
SCHED_RR
See Section 2.3.2.2 for a description of thread scheduling policies.
param
New values of the scheduling parameters associated with the scheduling
policy for the thread specified in thread. Valid values for the
sched_priority
field of a
sched_param
structure 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.
Additionally, the Threads Librray provides nonportable
priority range constants, as follows:
Low |
High |
PRI_FIFO_MIN
|
PRI_FIFO_MAX
|
PRI_RR_MIN
|
PRI_RR_MAX
|
PRI_OTHER_MIN
|
PRI_OTHER_MAX
|
PRI_FG_MIN_NP
|
PRI_FG_MAX_NP
|
PRI_BG_MIN_NP
|
PRI_BG_MAX_NP
|
The default priority varies by platform. On Tru64 UNIX, the default is
19 (that is, the POSIX priority of a normal timeshare process). On
other platforms the default priority is the midpoint between
PRI_FG_MIN_NP
and
PRI_FG_MAX_NP
. ( Section 2.3.6 describes how to specify priorities between the
minimum and maximum values.)
Description
This routine changes both the current scheduling policy and associated
scheduling parameters of the thread specified by thread to the
policy and associated parameters provided in policy and
param, respectively.
All currently implemented scheduling policies have one scheduling
parameter called
sched_priority
. For the policy you choose, you must specify an appropriate value in
the
sched_priority
field of the
sched_param
structure.
Changing the scheduling policy or priority, or both, of a thread can
cause it either to start executing or to be preempted by another
thread. A thread changes its own scheduling policy and priority by
using the handle returned by the
pthread_self()
routine.
This routine differs from
pthread_attr_setschedpolicy()
and
pthread_attr_setschedparam()
, in that those routines set the scheduling policy and parameter
attributes that are used to establish the scheduling priority and
scheduling policy of a new thread when it is created. However, this
routine changes the scheduling policy and parameters of an existing
thread.
Return Values If an error condition occurs, no scheduling policy or
parameters are changed for the target thread, 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
policy or
param is invalid.
|
[ENOTSUP]
|
An attempt was made to set the scheduling policy or a parameter to an
unsupported value.
|
[EPERM]
|
The caller does not have the appropriate privileges to set the
scheduling policy or parameters of the specified thread.
|
[ESRCH]
|
The value specified by
thread does not refer to an existing thread.
|
Associated Routines
pthread_attr_setschedparam()
pthread_attr_setschedpolicy()
pthread_create()
pthread_self()
sched_yield()
pthread_setspecific
Sets the thread-specific data value associated with the specified key
for the calling thread.
Syntax
pthread_setspecific( key , value );
Argument |
Data Type |
Access |
key
|
opaque pthread_key_t
|
read
|
value
|
void *
|
read
|
C Binding #include <pthread.h>
int
pthread_setspecific (
pthread_key_t key,
const void *value);
Arguments
key
Thread-specific key that identifies the thread-specific data to receive
value. This key value must be obtained from
pthread_key_create()
.
value
New thread-specific data value to associate with the specified key for
the calling thread.
Description
This routine sets the thread-specific data value associated with the
specified key for the current thread. If a value is defined
for the key in this thread (the current value is not NULL), the new
value is substituted for it. The key is obtained by a previous call to
pthread_key_create()
.
Different threads can bind different values to the same key. These
values are typically pointers to blocks of dynamically allocated memory
that are reserved for use by the calling thread.
Do not call this routine from a thread-specific data
destructor function.
Note that although the type for value
(void *)
implies that it represents an address, the type is being used as a
"universal scalar type." The Threads Library simply stores
value for later retrieval.
Return Values If an error condition occurs, this routine returns an
integer indicating the type of error. Possible return values are as
follows:
Return |
Description |
0
|
Successful completion.
|
[EINVAL]
|
The specified
key is invalid.
|
[ENOMEM]
|
Insufficient memory to associate the value with the key.
|
Associated Routines
pthread_getspecific()
pthread_key_create()
pthread_key_delete()
pthread_sigmask
Examine or change the calling thread's signal mask.
This routine is for Tru64 UNIX systems only.
Syntax
pthread_sigmask( how , set , oset );
Argument |
Data Type |
Access |
how
|
integer
|
read
|
set
|
sigset_t
|
read
|
oset
|
sigset_t
|
write
|
C Binding #include <pthread.h>
include <signal.h>
int
pthread_sigmask (
int how,
const sigset_t *set,
sigset_t *oset);
Arguments
how
Indicates the manner in which the set of masked signals is changed. The
optional values are as follows:
|
SIG_BLOCK
|
The resulting set is the union of the current set and the signal set
pointed to by the
set argument.
|
|
SIG_UNBLOCK
|
The resulting set is the intersection of the current set and the
complement of the signal set pointed to by the
set argument.
|
|
SIG_SETMASK
|
The resulting set is the signal set pointed to by the
set argument.
|
set
Specifies the signal set by pointing to a set of signals used to change
the blocked set. If this set value is NULL, the how
argument is ignored and the process signal mask is unchanged.
oset
Receives the value of the current signal mask (unless this value is
NULL).
Description
This routine examines or changes the calling thread's signal mask.
Typically, you use the
SIG_BLOCK
option for the how value to block signals during a critical
section of code, and then use this routine's
SIG_SETMASK
option to restore the mask to the previous value returned by the
previous call to the
pthread_sigmask()
routine.
If there are any unblocked signals pending after a call to this
routine, at least one of those signals will be delivered before this
routine returns.
This routine does not allow the SIGKILL or SIGSTOP signals to be
blocked. If a program attempts to block one of these signals,
pthread_sigmask()
gives no indication of the error.
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 for
how is invalid.
|
pthread_testcancel
Requests delivery of a pending cancelation request to the calling
thread.
Syntax
pthread_testcancel( );
C Binding #include <pthread.h>
void
pthread_testcancel (void);
Arguments
None
Description
This routine requests delivery of a pending cancelation request to the
calling thread. Thus, calling this routine creates a cancelation point
within the calling thread.
The cancelation request is delivered only if a request is pending for
the calling thread and the calling thread's cancelability state is
enabled. (A thread disables delivery of cancelation requests
to itself by calling
pthread_setcancelstate()
.)
When called within very long loops, this routine ensures that a pending
cancelation request is noticed by the calling thread within a
reasonable amount of time.
Return Values None Associated Routines
pthread_setcancelstate()
pthread_unlock_global_np
Unlocks the Threads Library global mutex.
Syntax
pthread_unlock_global_np( );
C Binding #include <pthread.h>
int
pthread_unlock_global_np (void);
Arguments
None
Description
This routine unlocks the Threads Library global mutex. Because the
global mutex is recursive, the unlock occurs when each call to
pthread_lock_global_np()
has been matched by a call to this routine. For example, if you called
pthread_lock_global_np()
three times,
pthread_unlock_global_np()
unlocks the global mutex when you call it the third time.
If no threads are waiting for the global mutex, it becomes unlocked
with no current owner. If one or more threads are waiting to lock the
global mutex, this routine causes one thread to unblock and to try to
acquire the global mutex. The scheduling policy is used by this routine
to determine which thread is awakened. For the policies
SCHED_FIFO
and
SCHED_RR
, a blocked thread is chosen in priority order, using
first-in/first-out (FIFO) within priorities.
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.
|
[EPERM]
|
The mutex is unlocked or owned by another thread.
|
Associated Routines
pthread_lock_global_np()
pthread_yield_np
Notifies the scheduler that the current thread is willing to release
its processor to other threads of the same or higher priority.
Syntax
pthread_yield_np( );
C Binding int
pthread_yield_np (void);
Arguments
None
Description
This routine notifies the thread scheduler that the current thread is
willing to release its processor to other threads of equivalent or
greater scheduling precedence. (A thread generally will release its
processor to a thread of a greater scheduling precedence without
calling this routine.) If no other threads of equivalent or greater
scheduling precedence are ready to execute, the thread continues.
This routine can allow knowledge of the details of an application to be
used to improve its performance. If a thread does not call
pthread_yield_np()
, other threads may be given the opportunity to run at arbitrary points
(possibly even when the interrupted thread holds a required resource).
By making strategic calls to
pthread_yield_np()
, other threads can be given the opportunity to run when the resources
are free. This improves performance by reducing contention for the
resource.
As a general guideline, consider calling this routine after a thread
has released a resource (such as a mutex) which is heavily contended
for by other threads. This can be especially important either if the
program is running on a uniprocessor machine, or if the thread acquires
and releases the resource inside a tight loop.
Use this routine carefully and sparingly, because misuse can cause
unnecessary context switching which will increase overhead and actually
degrade performance. For example, it is counter-productive for a thread
to yield while it holds a resource that the threads to which it is
yielding will need. Likewise, it is pointless to yield unless there is
likely to be another thread that is ready to run.
Note
pthread_yield_np()
is equivalent to
sched_yield()
. Use
sched_yield()
since it is part of the standard portable POSIX Threads Library.
|
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]
|
The routine
pthread_yield_np()
is not supported by this implementation.
|
Associated Routines
pthread_attr_setschedparam()
pthread_getschedparam()
pthread_setschedparam()
sched_get_priority_max
Returns the maximum priority for the specified scheduling policy.
Syntax
sched_get_priority_max( policy );
Argument |
Data Type |
Access |
policy
|
integer
|
read
|
C Binding #include <sched.h>
int
sched_get_priority_max (
int policy);
Arguments
policy
One of the scheduling policies, as defined in
sched.h
.
Description
This routine returns the maximum priority for the scheduling policy
specified in the policy argument. The argument value must be
one of the scheduling policies (
SCHED_FIFO
,
SCHED_RR
, or
SCHED_OTHER
), as defined in the
sched.h
header file.
No special privileges are required to use this routine.
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 of the
policy argument does not represent a defined scheduling policy.
|
|