87.4 – 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.
87.5 – Associated Routines
pthread_attr_setschedparam()
pthread_attr_setschedpolicy()
pthread_create()
pthread_self()
sched_yield()
88 – pthread_setspecific
Sets the thread-specific data value associated with the specified
key for the calling thread.
88.1 – C Binding
#include <pthread.h>
int
pthread_setspecific (
pthread_key_t key,
const void *value);
88.2 – 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.
88.3 – 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.
88.4 – 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.
88.5 – Associated Routines
pthread_getspecific()
pthread_key_create()
pthread_key_delete()
89 – pthread_testcancel
Requests delivery of a pending cancelation request to the calling
thread.
89.1 – C Binding
#include <pthread.h>
void
pthread_testcancel (void);
89.2 – Arguments
None
89.3 – 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.
89.4 – Return Values
None
89.5 – Associated Routines
pthread_setcancelstate()
90 – pthread_unlock_global_np
Unlocks the Threads Library global mutex.
90.1 – C Binding
#include <pthread.h>
int
pthread_unlock_global_np (void);
90.2 – Arguments
None
90.3 – 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.
90.4 – 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.
90.5 – Associated Routines
pthread_lock_global_np()
91 – 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();
91.1 – C Binding
int
pthread_yield_np (void);
91.2 – Arguments
None
91.3 – 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.
91.4 – 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.
91.5 – Associated Routines
pthread_attr_setschedparam()
pthread_getschedparam()
pthread_setschedparam()
92 – 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
92.1 – C Binding
#include <sched.h>
int
sched_get_priority_max (
int policy);
92.2 – Arguments
policy
One of the scheduling policies, as defined in sched.h.
92.3 – 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.
92.4 – 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.
93 – sched_get_priority_min
Returns the minimum priority for the specified scheduling policy.
Syntax
sched_get_priority_min(
policy);
Argument Data Type Access
policy integer read
93.1 – C Binding
#include <sched.h>
int
sched_get_priority_min (
int policy);
93.2 – Arguments
policy
One of the scheduling policies, as defined in sched.h.
93.3 – Description
This routine returns the minimum 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.
93.4 – 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.
94 – sched_yield
Yields execution to another thread.
Syntax
sched_yield();
94.1 – C Binding
#include <sched.h>
#include <unistd.h>
int
sched_yield (void);
94.2 – Arguments
None
94.3 – Description
In conformance with the IEEE POSIX.1-1996 standard, the sched_
yield() function causes the calling thread to yield execution
to another thread. It is useful when a thread running under the
SCHED_FIFO scheduling policy must allow another thread at the
same priority to run. The thread that is interrupted by sched_
yield() goes to the end of the queue for its priority.
If no other thread is runnable at the priority of the calling
thread, the calling thread continues to run.
Threads with higher priority are allowed to preempt the calling
thread, so the sched_yield() function has no effect on the
scheduling of higher- or lower-priority threads.
The sched_yield() routine takes no arguments. No special
privileges are needed to use the sched_yield() function.
94.4 – 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 sched_yield() is not supported by this
implementation.
94.5 – Associated Routines
pthread_attr_setschedparam()
pthread_getschedparam()
pthread_setschedparam()