VxWorks API Reference : OS Libraries
pthreadLib - POSIX 1003.1c thread library interfaces
pthreadLibInit( ) - initialize POSIX threads support
pthread_sigmask( ) - change and/or examine calling thread's signal mask (POSIX)
pthread_kill( ) - send a signal to a thread (POSIX)
pthread_mutexattr_init( ) - initialize mutex attributes object (POSIX)
pthread_mutexattr_destroy( ) - destroy mutex attributes object (POSIX)
pthread_mutexattr_setprotocol( ) - set protocol attribute in mutex attribut object (POSIX)
pthread_mutexattr_getprotocol( ) - get value of protocol in mutex attributes object (POSIX)
pthread_mutexattr_setprioceiling( ) - set prioceiling attribute in mutex attributes object (POSIX)
pthread_mutexattr_getprioceiling( ) - get the current value of the prioceiling attribute in a mutex attributes object (POSIX)
pthread_mutex_getprioceiling( ) - get the value of the prioceiling attribute of a mutex (POSIX)
pthread_mutex_setprioceiling( ) - dynamically set the prioceiling attribute of a mutex (POSIX)
pthread_mutex_init( ) - initialize mutex from attributes object (POSIX)
pthread_mutex_destroy( ) - destroy a mutex (POSIX)
pthread_mutex_lock( ) - lock a mutex (POSIX)
pthread_mutex_trylock( ) - lock mutex if it is available (POSIX)
pthread_mutex_unlock( ) - unlock a mutex (POSIX)
pthread_condattr_init( ) - initialize a condition attribute object (POSIX)
pthread_condattr_destroy( ) - destroy a condition attributes object (POSIX)
pthread_cond_init( ) - initialize condition variable (POSIX)
pthread_cond_destroy( ) - destroy a condition variable (POSIX)
pthread_cond_signal( ) - unblock a thread waiting on a condition (POSIX)
pthread_cond_broadcast( ) - unblock all threads waiting on a condition (POSIX)
pthread_cond_wait( ) - wait for a condition variable (POSIX)
pthread_cond_timedwait( ) - wait for a condition variable with a timeout (POSIX)
pthread_attr_setscope( ) - set contention scope for thread attributes (POSIX)
pthread_attr_getscope( ) - get contention scope from thread attributes (POSIX)
pthread_attr_setinheritsched( ) - set inheritsched attribute in thread attribute object (POSIX)
pthread_attr_getinheritsched( ) - get current value if inheritsched attribute in thread attributes object (POSIX)
pthread_attr_setschedpolicy( ) - set schedpolicy attribute in thread attributes object (POSIX)
pthread_attr_getschedpolicy( ) - get schedpolicy attribute from thread attributes object (POSIX)
pthread_attr_setschedparam( ) - set schedparam attribute in thread attributes object (POSIX)
pthread_attr_getschedparam( ) - get value of schedparam attribute from thread attributes object (POSIX)
pthread_getschedparam( ) - get value of schedparam attribute from a thread (POSIX)
pthread_setschedparam( ) - dynamically set schedparam attribute for a thread (POSIX)
pthread_attr_init( ) - initialize thread attributes object (POSIX)
pthread_attr_destroy( ) - destroy a thread attributes object (POSIX)
pthread_attr_setname( ) - set name in thread attribute object
pthread_attr_getname( ) - get name of thread attribute object
pthread_attr_setstacksize( ) - set stacksize attribute in thread attributes
pthread_attr_getstacksize( ) - get stack value of stacksize attribute from thread attributes object (POSIX)
pthread_attr_setstackaddr( ) - set stackaddr attribute in thread attributes object (POSIX)
pthread_attr_getstackaddr( ) - get value of stackaddr attribute from thread attributes object (POSIX)
pthread_attr_setdetachstate( ) - set detachstate attribute in thread attributes object (POSIX)
pthread_attr_getdetachstate( ) - get value of detachstate attribute from thread attributes object (POSIX)
pthread_create( ) - create a thread (POSIX)
pthread_detach( ) - dynamically detach a thread (POSIX)
pthread_join( ) - wait for a thread to terminate (POSIX)
pthread_exit( ) - terminate a thread (POSIX)
pthread_equal( ) - compare thread IDs (POSIX)
pthread_self( ) - get the calling thread's ID (POSIX)
pthread_once( ) - dynamic package initialization (POSIX)
pthread_key_create( ) - create a thread specific data key (POSIX)
pthread_setspecific( ) - set thread specific data (POSIX)
pthread_getspecific( ) - get thread specific data (POSIX)
pthread_key_delete( ) - delete a thread specific data key (POSIX)
pthread_cancel( ) - cancel execution of a thread (POSIX)
pthread_setcancelstate( ) - set cancellation state for calling thread (POSIX)
pthread_setcanceltype( ) - set cancellation type for calling thread (POSIX)
pthread_testcancel( ) - create a cancellation point in the calling thread (POSIX)
pthread_cleanup_push( ) - pushes a routine onto the cleanup stack (POSIX)
pthread_cleanup_pop( ) - pop a cleanup routine off the top of the stack (POSIX)
This library provides an implementation of POSIX 1003.1c threads for VxWorks. This provides an increased level of compatibility between VxWorks applications and those written for other operating systems that support the POSIX threads model (often called pthreads).
VxWorks is a task based operating system, rather than one implementing the process model in the POSIX sense. As a result of this, there are a few restrictions in the implementation, but in general, since tasks are roughly equivalent to threads, the pthreads support maps well onto VxWorks. The restrictions are explained in more detail in the following paragraphs.
To add POSIX threads support to a system, the component INCLUDE_POSIX_PTHREADS must be added.
Threads support also requires the POSIX scheduler to be included (see schedPxLib for more detail).
A thread is essentially a VxWorks task, with some additional characteristics. The first is detachability, where the creator of a thread can optionally block until the thread exits. The second is cancelability, where one task or thread can cause a thread to exit, possibly calling cleanup handlers. The next is private data, where data private to a thread is created, accessed and deleted via keys. Each thread has a unique ID. A thread's ID is different than it's VxWorks task ID.
Included with the POSIX threads facility is a mutual exclusion facility, or mutex. These are functionally similar to the VxWorks mutex semaphores (see semMLib for more detail), and in fact are implemented using a VxWorks mutex semaphore. The advantage they offer, like all of the POSIX libraries, is the ability to run software designed for POSIX platforms under VxWorks.
There are two types of locking protocols available, PTHREAD_PRIO_INHERIT and PTHREAD_PRIO_PROTECT. PTHREAD_PRIO_INHERIT maps to a semaphore create with SEM_PRIO_INHERIT set (see semMCreate for more detail). A thread locking a mutex created with its protocol attribute set to PTHREAD_PRIO_PROTECT has its priority elevated to that of of the prioceiling attribute of the mutex. When the mutex is unlocked, the priority of the calling thread is restored to its previous value.
Condition variables are another synchronization mechanism that is included in the POSIX threads library. A condition variable allows threads to block until some condition is met. There are really only two basic operations that a condition variable can be involved in: waiting and signalling. Condition variables are always associated with a mutex.
A thread can wait for a condition to become true by taking the mutex and then calling pthread_cond_wait( ). That function will release the mutex and wait for the condition to be signalled by another thread. When the condition is signalled, the function will re-acquire the mutex and return to the caller.
Condition variable support two types of signalling: single thread wake-up using pthread_cond_signal( ), and multiple thread wake-up using pthread_cond_broadcast( ). The latter of these will unblock all threads that were waiting on the specified condition variable.
It should be noted that condition variable signals are not related to POSIX signals. In fact, they are implemented using VxWorks semaphores.
All tasks, and therefore all POSIX threads, compete for CPU time together. For that reason the contention scope thread attribute is always PTHREAD_SCOPE_SYSTEM.
Since there is no notion of a process (in the POSIX sense), there is no notion of sharing of locks (mutexes) and condition variables between processes. As a result, the POSIX symbol _POSIX_THREAD_PROCESS_SHARED is not defined in this implementation, and the routines pthread_condattr_getpshared( ), pthread_condattr_setpshared( ), pthread_mutexattr_getpshared( ) are not implemented.
Also, since there are no processes in VxWorks, fork( ), wait( ), and pthread_atfork( ) are unimplemented.
VxWorks does not have password, user, or group databases, therefore there are no implementations of getlogin( ), getgrgid( ), getpwnam( ), getpwuid( ), getlogin_r( ), getgrgid_r( ), getpwnam_r( ), and getpwuid_r( ).
The default scheduling policy for a created thread is inherited from the system setting at the time of creation.
Scheduling policies under VxWorks are global; they are not set per-thread, as the POSIX model describes. As a result, the pthread scheduling routines, as well as the POSIX scheduling routines native to VxWorks, do not allow you to change the scheduling policy. Under VxWorks you may set the scheduling policy in a thread, but if it does not match the system's scheduling policy, an error is returned.
The detailed explanation for why this error occurs is a bit convoluted: technically the scheduling policy is an attribute of a thread (in that there are pthread_attr_getschedpolicy( ) and pthread_attr_setschedpolicy( ) functions that define what the thread's scheduling policy will be once it is created, and not what any thread should do at the time they are called). A situation arises where the scheduling policy in force at the time of a thread's creation is not the same as set in its attributes. In this case pthread_create( ) fails with an otherwise undocumented error ENOTTY.
The bottom line is that under VxWorks, if you wish to specify the scheduling policy of a thread, you must set the desired global scheduling policy to match. Threads must then adhere to that scheduling policy, or use the PTHREAD_INHERIT_SCHED mode to inherit the current mode and creator's priority.
Each time a thread is created, the pthreads library allocates resources on behalf of it. Each time a VxWorks task (i.e. one not created by the pthread_create( ) function) uses a POSIX threads feature such as thread private data or pushes a cleanup handler, the pthreads library creates resources on behalf of that task as well.
Asynchronous thread cancellation is accomplished by way of a signal. A special signal, SIGCANCEL, has been set aside in this version of VxWorks for this purpose. Applications should take care not to block or handle SIGCANCEL.
pthread function Implemented? Note(s) pthread_attr_destroy Yes pthread_attr_getdetachstate Yes pthread_attr_getinheritsched Yes pthread_attr_getschedparam Yes pthread_attr_getschedpolicy Yes pthread_attr_getscope Yes pthread_attr_getstackaddr Yes pthread_attr_getstacksize Yes pthread_attr_init Yes pthread_attr_setdetachstate Yes pthread_attr_setinheritsched Yes pthread_attr_setschedparam Yes pthread_attr_setschedpolicy Yes pthread_attr_setscope Yes 2 pthread_attr_setstackaddr Yes pthread_attr_setstacksize Yes pthread_atfork No 1 pthread_cancel Yes 5 pthread_cleanup_pop Yes pthread_cleanup_push Yes pthread_condattr_destroy Yes pthread_condattr_getpshared No 3 pthread_condattr_init Yes pthread_condattr_setpshared No 3 pthread_cond_broadcast Yes pthread_cond_destroy Yes pthread_cond_init Yes pthread_cond_signal Yes pthread_cond_timedwait Yes pthread_cond_wait Yes pthread_create Yes pthread_detach Yes pthread_equal Yes pthread_exit Yes pthread_getschedparam Yes 4 pthread_getspecific Yes pthread_join Yes pthread_key_create Yes pthread_key_delete Yes pthread_kill Yes pthread_once Yes pthread_self Yes pthread_setcancelstate Yes pthread_setcanceltype Yes pthread_setschedparam Yes 4 pthread_setspecific Yes pthread_sigmask Yes pthread_testcancel Yes pthread_mutexattr_destroy Yes pthread_mutexattr_getprioceiling Yes pthread_mutexattr_getprotocol Yes pthread_mutexattr_getpshared No 3 pthread_mutexattr_init Yes pthread_mutexattr_setprioceiling Yes pthread_mutexattr_setprotocol Yes pthread_mutexattr_setpshared No 3 pthread_mutex_destroy Yes pthread_mutex_getprioceiling Yes pthread_mutex_init Yes pthread_mutex_lock Yes pthread_mutex_setprioceiling Yes pthread_mutex_trylock Yes pthread_mutex_unlock Yes getlogin_r No 6 getgrgid_r No 6 getpwnam_r No 6 getpwuid_r No 6
1 The pthread_atfork( ) function is not implemented since fork( ) is not implemented in VxWorks. 2 The contention scope thread scheduling attribute is always PTHREAD_SCOPE_SYSTEM, since threads (i.e. tasks) contend for resources with all other threads in the system. 3 The routines pthread_condattr_getpshared( ), pthread_attr_setpshared( ), pthread_mutexattr_getpshared( ) and pthread_mutexattr_setpshared( ) are not supported, since these interfaces describe how condition variables and mutexes relate to a process, and VxWorks does not implement a process model. 4 The default scheduling policy is inherited from the current system setting. The POSIX model of per-thread scheduling policies is not supported, since a basic tenet of the design of VxWorks is a system-wide scheduling policy. 5 Thread cancellation is supported in appropriate pthread routines and those routines already supported by VxWorks. However, the complete list of cancellation points specified by POSIX is not supported because routines such as msync( ), fcntl( ), tcdrain( ), and wait( ) are not implemented by VxWorks. 6 The routines getlogin_r( ), getgrgid_r( ), getpwnam_r( ), and getpwuid_r( ) are not implemented.
pthread.h
taskLib, semMLib, semPxLib, VxWorks Programmer's Guide: Multitasking
pthreadLibInit( ) - initialize POSIX threads support
void pthreadLibInit (void)
This routine initializes the POSIX threads (pthreads) support for VxWorks. It should be called before any POSIX threads functions are used; normally it will be called as part of the kernel's initialization sequence.
N/A
pthread_sigmask( ) - change and/or examine calling thread's signal mask (POSIX)
int pthread_sigmask ( int how, /* method for changing set */ const sigset_t * set, /* new set of signals */ sigset_t * oset /* old set of signals */ )
This routine changes the signal mask for the calling thread as described by the how and set arguments. If oset is not NULL, the previous signal mask is stored in the location pointed to by it.
The value of how indicates the manner in which the set is changed and consists of one of the following defined in signal.h:
- SIG_BLOCK
- The resulting set is the union of the current set and the signal set pointed to by set.
- SIG_UNBLOCK
- The resulting set is the intersection of the current set and the complement of the signal set pointed to by set.
- SIG_SETMASK
- The resulting set is the signal set pointed to by oset.
On success zero; on failure a non-zero error code is returned.
EINVAL
pthreadLib, kill( ), pthread_kill( ), sigprocmask( ), sigaction( ), sigsuspend( ), sigwait( )
pthread_kill( ) - send a signal to a thread (POSIX)
int pthread_kill ( pthread_t thread, /* thread to signal */ int sig /* signal to send */ )
This routine sends signal number sig to the thread specified by thread. The signal is delivered and handled as described for the kill( ) function.
On success zero; on failure a non-zero error code.
ESRCH, EINVAL
pthreadLib, kill( ), pthread_sigmask( ), sigprocmask( ), sigaction( ), sigsuspend( ), sigwait( )
pthread_mutexattr_init( ) - initialize mutex attributes object (POSIX)
int pthread_mutexattr_init ( pthread_mutexattr_t * pAttr /* mutex attributes */ )
This routine initializes the mutex attribute object pAttr and fills it with default values for the attributes as defined by the POSIX specification.
On success zero; on failure a non-zero error code.
EINVAL
pthreadLib, pthread_mutexattr_destroy( ), pthread_mutexattr_getprioceiling( ), pthread_mutexattr_getprotocol( ), pthread_mutexattr_setprioceiling( ), pthread_mutexattr_setprotocol( ), pthread_mutex_init( )
pthread_mutexattr_destroy( ) - destroy mutex attributes object (POSIX)
int pthread_mutexattr_destroy ( pthread_mutexattr_t * pAttr /* mutex attributes */ )
This routine destroys a mutex attribute object. The mutex attribute object must not be reused until it is reinitialized.
On success zero; on failure a non-zero error code.
EINVAL
pthreadLib, pthread_mutexattr_getprioceiling( ), pthread_mutexattr_getprotocol( ), pthread_mutexattr_init( ), pthread_mutexattr_setprioceiling( ), pthread_mutexattr_setprotocol( ), pthread_mutex_init( )
pthread_mutexattr_setprotocol( ) - set protocol attribute in mutex attribut object (POSIX)
int pthread_mutexattr_setprotocol ( pthread_mutexattr_t * pAttr, /* mutex attributes */ int protocol /* new protocol */ )
This function selects the locking protocol to be used when a mutex is created using this attributes object. The protocol to be selected is either PTHREAD_PRIO_INHERIT or PTHREAD_PRIO_PROTECT.
On success zero; on failure a non-zero error code.
EINVAL, ENOTSUP
pthreadLib, pthread_mutexattr_destroy( ), pthread_mutexattr_getprioceiling( ), pthread_mutexattr_getprotocol( ), pthread_mutexattr_init( ), pthread_mutexattr_setprioceiling( ), pthread_mutex_init( )
pthread_mutexattr_getprotocol( ) - get value of protocol in mutex attributes object (POSIX)
int pthread_mutexattr_getprotocol ( pthread_mutexattr_t * pAttr, /* mutex attributes */ int * pProtocol /* current protocol (out) */ )
This function gets the current value of the protocol attribute in a mutex attributes object.
On success zero; on failure a non-zero error code.
EINVAL
pthreadLib, pthread_mutexattr_destroy( ), pthread_mutexattr_getprioceiling( ), pthread_mutexattr_init( ), pthread_mutexattr_setprioceiling( ), pthread_mutexattr_setprotocol( ), pthread_mutex_init( )
pthread_mutexattr_setprioceiling( ) - set prioceiling attribute in mutex attributes object (POSIX)
int pthread_mutexattr_setprioceiling ( pthread_mutexattr_t * pAttr, /* mutex attributes */ int prioceiling /* new priority ceiling */ )
This function sets the value of the prioceiling attribute in a mutex attributes object. Unless the protocol attribute is set to PTHREAD_PRIO_PROTECT, this attribute is ignored.
On success zero; on failure a non-zero error code.
EINVAL
pthreadLib, pthread_mutexattr_destroy( ), pthread_mutexattr_getprioceiling( ), pthread_mutexattr_getprotocol( ), pthread_mutexattr_init( ), pthread_mutexattr_setprotocol( ), pthread_mutex_init( )
pthread_mutexattr_getprioceiling( ) - get the current value of the prioceiling attribute in a mutex attributes object (POSIX)
int pthread_mutexattr_getprioceiling ( pthread_mutexattr_t * pAttr, /* mutex attributes */ int * pPrioceiling /* current priority ceiling (out) */ )
This function gets the current value of the prioceiling attribute in a mutex attributes object. Unless the value of the protocol attribute is PTHREAD_PRIO_PROTECT, this value is ignored.
On success zero; on failure a non-zero error code.
EINVAL
pthreadLib, pthread_mutexattr_destroy( ), pthread_mutexattr_getprotocol( ), pthread_mutexattr_init( ), pthread_mutexattr_setprioceiling( ), pthread_mutexattr_setprotocol( ), pthread_mutex_init( )
pthread_mutex_getprioceiling( ) - get the value of the prioceiling attribute of a mutex (POSIX)
int pthread_mutex_getprioceiling ( pthread_mutex_t * pMutex, /* POSIX mutex */ int * pPrioceiling /* current priority ceiling (out) */ )
This function gets the current value of the prioceiling attribute of a mutex. Unless the mutex was created with a protocol attribute value of PTHREAD_PRIO_PROTECT, this value is meaningless.
On success zero; on failure a non-zero error code.
EINVAL
pthreadLib, pthread_mutex_setprioceiling( ), pthread_mutexattr_getprioceiling( ), pthread_mutexattr_setprioceiling( )
pthread_mutex_setprioceiling( ) - dynamically set the prioceiling attribute of a mutex (POSIX)
int pthread_mutex_setprioceiling ( pthread_mutex_t * pMutex, /* POSIX mutex */ int prioceiling, /* new priority ceiling */ int * pOldPrioceiling /* old priority ceiling (out) */ )
This function dynamically sets the value of the prioceiling attribute of a mutex. Unless the mutex was created with a protocol value of PTHREAD_PRIO_PROTECT, this function does nothing.
On success zero; on failure a non-zero error code.
EINVAL, EPERM, S_objLib_OBJ_ID_ERROR, S_semLib_NOT_ISR_CALLABLE
pthreadLib, pthread_mutex_getprioceiling( ), pthread_mutexattr_getprioceiling( ), pthread_mutexattr_setprioceiling( )
pthread_mutex_init( ) - initialize mutex from attributes object (POSIX)
int pthread_mutex_init ( pthread_mutex_t * pMutex, /* POSIX mutex */ const pthread_mutexattr_t * pAttr /* mutex attributes */ )
This routine initializes the mutex object pointed to by pMutex according to the mutex attributes specified in pAttr. If pAttr is NULL, default attributes are used as defined in the POSIX specification.
On success zero; on failure a non-zero error code.
EINVAL, EBUSY
pthreadLib, semLib, semMLib, pthread_mutex_destroy( ), pthread_mutex_lock( ), pthread_mutex_trylock( ), pthread_mutex_unlock( ), pthread_mutexattr_init( ), semMCreate( )
pthread_mutex_destroy( ) - destroy a mutex (POSIX)
int pthread_mutex_destroy ( pthread_mutex_t * pMutex /* POSIX mutex */ )
This routine destroys a mutex object, freeing the resources it might hold. The mutex must be unlocked when this function is called, otherwise it will return an error (EBUSY).
On success zero; on failure a non-zero error code.
EINVAL, EBUSY
pthreadLib, semLib, semMLib, pthread_mutex_init( ), pthread_mutex_lock( ), pthread_mutex_trylock( ), pthread_mutex_unlock( ), pthread_mutexattr_init( ), semDelete( )
pthread_mutex_lock( ) - lock a mutex (POSIX)
int pthread_mutex_lock ( pthread_mutex_t * pMutex /* POSIX mutex */ )
This routine locks the mutex specified by pMutex. If the mutex is currently unlocked, it becomes locked, and is said to be owned by the calling thread. In this case pthread_mutex_lock( ) returns immediately.
If the mutex is already locked by another thread, pthread_mutex_lock( ) blocks the calling thread until the mutex is unlocked by its current owner.
If it is already locked by the calling thread, pthread_mutex_lock will deadlock on itself and the thread will block indefinitely.
On success zero; on failure a non-zero error code.
EINVAL
pthreadLib, semLib, semMLib, pthread_mutex_init( ), pthread_mutex_lock( ), pthread_mutex_trylock( ), pthread_mutex_unlock( ), pthread_mutexattr_init( ), semTake( )
pthread_mutex_trylock( ) - lock mutex if it is available (POSIX)
int pthread_mutex_trylock ( pthread_mutex_t * pMutex /* POSIX mutex */ )
This routine locks the mutex specified by pMutex. If the mutex is currently unlocked, it becomes locked and owned by the calling thread. In this case pthread_mutex_trylock( ) returns immediately.
If the mutex is already locked by another thread, pthread_mutex_trylock( ) returns immediately with the error code EBUSY.
On success zero; on failure a non-zero error code.
EINVAL, EBUSY
pthreadLib, semLib, semMLib, pthread_mutex_init( ), pthread_mutex_lock( ), pthread_mutex_trylock( ), pthread_mutex_unlock( ), pthread_mutexattr_init( ), semTake( )
pthread_mutex_unlock( ) - unlock a mutex (POSIX)
int pthread_mutex_unlock ( pthread_mutex_t * pMutex )
This routine unlocks the mutex specified by pMutex. If the calling thread is not the current owner of the mutex, pthread_mutex_unlock( ) returns with the error code EPERM.
On success zero; on failure a non-zero error code.
EINVAL, EPERM, S_objLib_OBJ_ID_ERROR, S_semLib_NOT_ISR_CALLABLE
pthreadLib, semLib, semMLib, pthread_mutex_init( ), pthread_mutex_lock( ), pthread_mutex_trylock( ), pthread_mutex_unlock( ), pthread_mutexattr_init( ), semGive( )
pthread_condattr_init( ) - initialize a condition attribute object (POSIX)
int pthread_condattr_init ( pthread_condattr_t * pAttr /* condition variable attributes */ )
This routine initializes the condition attribute object pAttr and fills it with default values for the attributes.
On success zero; on failure a non-zero error code.
EINVAL
pthreadLib, pthread_cond_init( ), pthread_condattr_destroy( )
pthread_condattr_destroy( ) - destroy a condition attributes object (POSIX)
int pthread_condattr_destroy ( pthread_condattr_t * pAttr /* condition variable attributes */ )
This routine destroys the condition attribute object pAttr. It must not be reused until it is reinitialized.
Always returns zero.
None.
pthreadLib, pthread_cond_init( ), pthread_condattr_init( )
pthread_cond_init( ) - initialize condition variable (POSIX)
int pthread_cond_init ( pthread_cond_t * pCond, /* condition variable */ pthread_condattr_t * pAttr /* condition variable attributes */ )
This function initializes a condition variable. A condition variable is a synchronization device that allows threads to block until some predicate on shared data is satisfied. The basic operations on conditions are to signal the condition (when the predicate becomes true), and wait for the condition, blocking the thread until another thread signals the condition.
A condition variable must always be associated with a mutex to avoid a race condition between the wait and signal operations.
If pAttr is NULL then the default attributes are used as specified by POSIX; if pAttr is non-NULL then it is assumed to point to a condition attributes object initialized by pthread_condattr_init( ), and those are the attributes used to create the condition variable.
On success zero; on failure a non-zero error code.
EINVAL, EBUSY
pthreadLib, pthread_condattr_init( ), pthread_condattr_destroy( ), pthread_cond_broadcast( ), pthread_cond_destroy( ), pthread_cond_signal( ), pthread_cond_timedwait( ), pthread_cond_wait( )
pthread_cond_destroy( ) - destroy a condition variable (POSIX)
int pthread_cond_destroy ( pthread_cond_t * pCond /* condition variable */ )
This routine destroys the condition variable pointed to by pCond. No threads can be waiting on the condition variable when this function is called. If there are threads waiting on the condition variable, then pthread_cond_destroy( ) returns EBUSY.
On success zero; on failure a non-zero error code.
EINVAL, EBUSY
pthreadLib, pthread_condattr_init( ), pthread_condattr_destroy( ), pthread_cond_broadcast( ), pthread_cond_init( ), pthread_cond_signal( ), pthread_cond_timedwait( ), pthread_cond_wait( )
pthread_cond_signal( ) - unblock a thread waiting on a condition (POSIX)
int pthread_cond_signal ( pthread_cond_t * pCond )
This routine unblocks one thread waiting on the specified condition variable pCond. If no threads are waiting on the condition variable then this routine does nothing; if more than one thread is waiting, then one will be released, but it is not specified which one.
On success zero; on failure a non-zero error code.
EINVAL
pthreadLib, pthread_condattr_init( ), pthread_condattr_destroy( ), pthread_cond_broadcast( ), pthread_cond_destroy( ), pthread_cond_init( ), pthread_cond_timedwait( ), pthread_cond_wait( )
pthread_cond_broadcast( ) - unblock all threads waiting on a condition (POSIX)
int pthread_cond_broadcast ( pthread_cond_t * pCond )
This function unblocks all threads blocked on the condition variable pCond. Nothing happens if no threads are waiting on the specified condition variable.
On success zero; on failure a non-zero error code.
EINVAL
pthreadLib, pthread_condattr_init( ), pthread_condattr_destroy( ), pthread_cond_destroy( ), pthread_cond_init( ), pthread_cond_signal( ), pthread_cond_timedwait( ), pthread_cond_wait( )
pthread_cond_wait( ) - wait for a condition variable (POSIX)
int pthread_cond_wait ( pthread_cond_t * pCond, /* condition variable */ pthread_mutex_t * pMutex /* POSIX mutex */ )
This function atomically releases the mutex pMutex and waits for the condition variable pCond to be signalled by another thread. The mutex must be locked by the calling thread when pthread_cond_wait( ) is called; if it is not then this function returns an error (EINVAL).
Before returning to the calling thread, pthread_cond_wait( ) re-acquires the mutex.
On success zero; on failure a non-zero error code.
EINVAL
pthreadLib, pthread_condattr_init( ), pthread_condattr_destroy( ), pthread_cond_broadcast( ), pthread_cond_destroy( ), pthread_cond_init( ), pthread_cond_signal( ), pthread_cond_timedwait( )
pthread_cond_timedwait( ) - wait for a condition variable with a timeout (POSIX)
int pthread_cond_timedwait ( pthread_cond_t * pCond, /* condition variable */ pthread_mutex_t * pMutex, /* POSIX mutex */ const struct timespec * pAbstime /* timeout time */ )
This function atomically releases the mutex pMutex and waits for another thread to signal the condition variable pCond. As with pthread_cond_wait( ), the mutex must be locked by the calling thread when pthread_cond_timedwait( ) is called.
If the condition variable is signalled before the system time reaches the time specified by pAbsTime, then the mutex is re-acquired and the calling thread unblocked.
If the system time reaches or exceeds the time specified by pAbsTime before the condition is signalled, then the mutex is re-acquired, the thread unblocked and ETIMEDOUT returned.
The timeout is specified as an absolute value of the system clock in a timespec structure (see clock_gettime( ) for more information). This is different from most VxWorks timeouts which are specified in ticks relative to the current time.
On success zero; on failure a non-zero error code.
EINVAL, ETIMEDOUT
pthreadLib, pthread_condattr_init( ), pthread_condattr_destroy( ), pthread_cond_broadcast( ), pthread_cond_destroy( ), pthread_cond_init( ), pthread_cond_signal( ), pthread_cond_wait( )
pthread_attr_setscope( ) - set contention scope for thread attributes (POSIX)
int pthread_attr_setscope ( pthread_attr_t * pAttr, /* thread attributes object */ int contentionScope /* new contention scope */ )
For VxWorks PTHREAD_SCOPE_SYSTEM is the only supported contention scope. Any other value passed to this function will result in EINVAL being returned.
On success zero; on failure a non-zero error code.
EINVAL
pthreadLib, pthread_attr_getscope( ), pthread_attr_init( )
pthread_attr_getscope( ) - get contention scope from thread attributes (POSIX)
int pthread_attr_getscope ( const pthread_attr_t * pAttr, /* thread attributes object */ int * pContentionScope /* contention scope (out) */ )
Reads the current contention scope setting from a thread attributes object. For VxWorks this is always PTHREAD_SCOPE_SYSTEM. If the thread attributes object is uninitialized then EINVAL will be returned. The contention scope is returned in the location pointed to by pContentionScope.
On success zero; on failure a non-zero error code.
EINVAL
pthreadLib, pthread_attr_init( ), pthread_attr_setscope( )
pthread_attr_setinheritsched( ) - set inheritsched attribute in thread attribute object (POSIX)
int pthread_attr_setinheritsched ( pthread_attr_t * pAttr, /* thread attributes object */ int inheritsched /* inheritance mode */ )
This routine sets the scheduling inheritance to be used when creating a thread with the thread attributes object specified by pAttr.
Possible values are:
- PTHREAD_INHERIT_SCHED
- Inherit scheduling parameters from parent thread.
- PTHREAD_EXPLICIT_SCHED
- Use explicitly provided scheduling parameters (i.e. those specified in the thread attributes object).
On success zero; on failure a non-zero error code.
EINVAL
pthreadLib, pthread_attr_getinheritsched( ), pthread_attr_init( ), pthread_attr_setschedparam( ), pthread_attr_setschedpolicy( )
pthread_attr_getinheritsched( ) - get current value if inheritsched attribute in thread attributes object (POSIX)
int pthread_attr_getinheritsched ( const pthread_attr_t * pAttr, /* thread attributes object */ int * pInheritsched /* inheritance mode (out) */ )
This routine gets the scheduling inheritance value from the thread attributes object pAttr.
Possible values are:
- PTHREAD_INHERIT_SCHED
- Inherit scheduling parameters from parent thread.
- PTHREAD_EXPLICIT_SCHED
- Use explicitly provided scheduling parameters (i.e. those specified in the thread attributes object).
On success zero; on failure a non-zero error code.
EINVAL
pthreadLib, pthread_attr_init( ), pthread_attr_getschedparam( ), pthread_attr_getschedpolicy( ) pthread_attr_setinheritsched( )
pthread_attr_setschedpolicy( ) - set schedpolicy attribute in thread attributes object (POSIX)
int pthread_attr_setschedpolicy ( pthread_attr_t * pAttr, /* thread attributes */ int policy /* new policy */ )
Select the thread scheduling policy. The default scheduling policy is to inherit the current system setting. Unlike the POSIX model, scheduling policies under VxWorks are global. If a scheduling policy is being set explicitly, the PTHREAD_EXPLICIT_SCHED mode must be set (see pthread_attr_setinheritsched( ) for information), and the selected scheduling policy must match the global scheduling policy in place at the time; failure to do so will result in pthread_create( ) failing with the non-POSIX error ENOTTY.
POSIX defines the following policies:
- SCHED_RR
- Realtime, round-robin scheduling.
- SCHED_FIFO
- Realtime, first-in first-out scheduling.
- SCHED_OTHER
- Other, non-realtime scheduling.
VxWorks only supports SCHED_RR and SCHED_FIFO.
On success zero; on failure a non-zero error code.
EINVAL
pthreadLib, schedPxLib, pthread_attr_getschedpolicy( ), pthread_attr_init( ), pthread_attr_setinheritsched( ), pthread_getschedparam( ), pthread_setschedparam( ), sched_setscheduler( ), sched_getscheduler( )
pthread_attr_getschedpolicy( ) - get schedpolicy attribute from thread attributes object (POSIX)
int pthread_attr_getschedpolicy ( const pthread_attr_t * pAttr, /* thread attributes */ int * pPolicy /* current policy (out) */ )
This routine returns, via the pointer pPolicy, the current scheduling policy in the thread attributes object specified by pAttr. Possible values for VxWorks systems are SCHED_RR and SCHED_FIFO; SCHED_OTHER is not supported.
On success zero; on failure a non-zero error code.
EINVAL
pthreadLib, schedPxLib, pthread_attr_init( ), pthread_attr_setschedpolicy( ), pthread_getschedparam( ), pthread_setschedparam( ), sched_setscheduler( ), sched_getscheduler( )
pthread_attr_setschedparam( ) - set schedparam attribute in thread attributes object (POSIX)
int pthread_attr_setschedparam ( pthread_attr_t * pAttr, /* thread attributes */ const struct sched_param * pParam /* new parameters */ )
Set the scheduling parameters in the thread attributes object pAttr. The scheduling parameters are essentially the thread's priority.
On success zero; on failure a non-zero error code.
EINVAL
pthreadLib, schedPxLib, pthread_attr_getschedparam( ), pthread_attr_init( ), pthread_getschedparam( ), pthread_setschedparam( ), sched_getparam( ), sched_setparam( )
pthread_attr_getschedparam( ) - get value of schedparam attribute from thread attributes object (POSIX)
int pthread_attr_getschedparam ( const pthread_attr_t * pAttr, /* thread attributes */ struct sched_param * pParam /* current parameters (out) */ )
Return, via the pointer pParam, the current scheduling parameters from the thread attributes object pAttr.
On success zero; on failure a non-zero error code.
EINVAL
pthreadLib, schedPxLib, pthread_attr_init( ), pthread_attr_setschedparam( ), pthread_getschedparam( ), pthread_setschedparam( ), sched_getparam( ), sched_setparam( )
pthread_getschedparam( ) - get value of schedparam attribute from a thread (POSIX)
int pthread_getschedparam ( pthread_t thread, /* thread */ int * pPolicy, /* current policy (out) */ struct sched_param * pParam /* current parameters (out) */ )
This routine reads the current scheduling parameters and policy of the thread specified by thread. The information is returned via pPolicy and pParam.
On success zero; on failure a non-zero error code.
ESRCH
pthreadLib, schedPxLib, pthread_attr_getschedparam( ) pthread_attr_getschedpolicy( ) pthread_attr_setschedparam( ) pthread_attr_setschedpolicy( ) pthread_setschedparam( ), sched_getparam( ), sched_setparam( )
pthread_setschedparam( ) - dynamically set schedparam attribute for a thread (POSIX)
int pthread_setschedparam ( pthread_t thread, /* thread */ int policy, /* new policy */ const struct sched_param * pParam /* new parameters */ )
This routine will set the scheduling parameters (pParam) and policy (policy) for the thread specified by thread.
In VxWorks the scheduling policy is global and not set on a per-thread basis; if the selected policy does not match the current global setting then this function will return an error (EINVAL).
On success zero; on failure a non-zero error code.
EINVAL, ESRCH
pthreadLib, schedPxLib, pthread_attr_getschedparam( ) pthread_attr_getschedpolicy( ) pthread_attr_setschedparam( ) pthread_attr_setschedpolicy( ) pthread_getschedparam( ), sched_getparam( ), sched_setparam( )
pthread_attr_init( ) - initialize thread attributes object (POSIX)
int pthread_attr_init ( pthread_attr_t * pAttr /* thread attributes */ )
This routine initializes a thread attributes object. If pAttr is NULL then this function will return EINVAL.
The attributes that are set by default are as follows:
- Stack Address
- NULL - allow the system to allocate the stack.
- Stack Size
- 0 - use the VxWorks taskLib default stack size.
- Detach State
- PTHREAD_CREATE_JOINABLE
- Contention Scope
- PTHREAD_SCOPE_SYSTEM
- Scheduling Inheritance
- PTHREAD_INHERIT_SCHED
- Scheduling Policy
- SCHED_RR
- Scheduling Priority
- Use pthreadLib default priority
Note that the scheduling policy and priority values are only used if the scheduling inheritance mode is changed to PTHREAD_EXPLICIT_SCHED - see pthread_attr_setinheritsched( ) for information.
On success zero; on failure a non-zero error code.
EINVAL
pthreadLib, pthread_attr_destroy( ), pthread_attr_getdetachstate( ), pthread_attr_getinheritsched( ), pthread_attr_getschedparam( ), pthread_attr_getschedpolicy( ), pthread_attr_getscope( ), pthread_attr_getstackaddr( ), pthread_attr_getstacksize( ), pthread_attr_setdetachstate( ), pthread_attr_setinheritsched( ), pthread_attr_setschedparam( ), pthread_attr_setschedpolicy( ), pthread_attr_setscope( ), pthread_attr_setstackaddr( ), pthread_attr_setstacksize( )
pthread_attr_destroy( ) - destroy a thread attributes object (POSIX)
int pthread_attr_destroy ( pthread_attr_t * pAttr /* thread attributes */ )
Destroy the thread attributes object pAttr. It should not be re-used until it has been reinitialized.
On success zero; on failure a non-zero error code.
EINVAL
pthreadLib, pthread_attr_init( )
pthread_attr_setname( ) - set name in thread attribute object
int pthread_attr_setname ( pthread_attr_t * pAttr, char * name )
This routine sets the name in the specified thread attributes object, pAttr.
Always returns
None.
pthreadLib, pthread_attr_getname( ),
pthread_attr_getname( ) - get name of thread attribute object
int pthread_attr_getname ( pthread_attr_t * pAttr, char * *name )
This routine gets the name in the specified thread attributes object, pAttr.
Always returns zero
None.
pthreadLib, pthread_attr_setname( ),
pthread_attr_setstacksize( ) - set stacksize attribute in thread attributes
int pthread_attr_setstacksize ( pthread_attr_t * pAttr, /* thread attributes */ size_t stacksize /* new stack size */ )
object (POSIX)
This routine sets the thread stack size in the specified thread attributes object, pAttr.
Always returns zero.
None.
pthreadLib, pthread_attr_getstacksize( ), pthread_attr_init( )
pthread_attr_getstacksize( ) - get stack value of stacksize attribute from thread attributes object (POSIX)
int pthread_attr_getstacksize ( const pthread_attr_t * pAttr, /* thread attributes */ size_t * pStacksize /* current stack size (out) */ )
This routine gets the current stack size from the thread attributes object pAttr and places it in the location pointed to by pStacksize.
Always returns zero.
None.
pthreadLib, pthread_attr_init( ), pthread_attr_setstacksize( )
pthread_attr_setstackaddr( ) - set stackaddr attribute in thread attributes object (POSIX)
int pthread_attr_setstackaddr ( pthread_attr_t * pAttr, /* thread attributes */ void * pStackaddr /* new stack address */ )
This routine sets the stack address in the thread attributes object pAttr to be pStackaddr.
It is important to note that the size of this stack must be large enough to also include the task's TCB. The size of the TCB varies from architecture to architecture but can be determined by calling sizeof (WIND_TCB).
Stack size is set using the routine pthread_attr_setstacksize( );
Always returns zero.
None.
pthreadLib, pthread_attr_getstacksize( ), pthread_attr_setstacksize( ), pthread_attr_init( )
pthread_attr_getstackaddr( ) - get value of stackaddr attribute from thread attributes object (POSIX)
int pthread_attr_getstackaddr ( const pthread_attr_t * pAttr, /* thread attributes */ void * *ppStackaddr /* current stack address (out) */ )
This routine returns the stack address from the thread attributes object pAttr in the location pointed to by ppStackaddr.
Always returns zero.
None.
pthreadLib, pthread_attr_init( ), pthread_attr_setstacksize( )
pthread_attr_setdetachstate( ) - set detachstate attribute in thread attributes object (POSIX)
int pthread_attr_setdetachstate ( pthread_attr_t * pAttr, /* thread attributes */ int detachstate /* new detach state */ )
This routine sets the detach state in the thread attributes object pAttr. The new detach state specified by detachstate must be one of PTHREAD_CREATE_DETACHED or PTHREAD_CREATE_JOINABLE. Any other values will cause an error to be returned (EINVAL).
On success zero; on failure a non-zero error code.
EINVAL
pthreadLib, pthread_attr_getdetachstate( ), pthread_attr_init( )
pthread_attr_getdetachstate( ) - get value of detachstate attribute from thread attributes object (POSIX)
int pthread_attr_getdetachstate ( const pthread_attr_t * pAttr, /* thread attributes */ int * pDetachstate /* current detach state (out) */ )
This routine returns the current detach state specified in the thread attributes object pAttr. The value is stored in the location pointed to by pDetachstate. Possible values for the detach state are: PTHREAD_CREATE_DETACHED and PTHREAD_CREATE_JOINABLE.
Always returns zero.
None.
pthreadLib, pthread_attr_init( ), pthread_attr_setdetachstate( )
pthread_create( ) - create a thread (POSIX)
int pthread_create ( pthread_t * pThread, /* Thread ID (out) */ const pthread_attr_t * pAttr, /* Thread attributes object */ void * (* startRoutine)(void * ),/* Entry function */ void * arg /* Entry function argument */ )
This routine creates a new thread and if successful writes its ID into the location pointed to by pThread. If pAttr is NULL then default attributes are used. The new thread executes startRoutine with arg as its argument.
On success zero; on failure a non-zero error code.
EINVAL, EAGAIN
pthreadLib, pthread_exit( ), pthread_join( )
pthread_detach( ) - dynamically detach a thread (POSIX)
int pthread_detach ( pthread_t thread /* thread to detach */ )
This routine puts the thread thread into the detached state. This prevents other threads from synchronizing on the termination of the thread using pthread_join( ).
On success zero; on failure a non-zero error code.
EINVAL, ESRCH
pthread_join( ) - wait for a thread to terminate (POSIX)
int pthread_join ( pthread_t thread, /* thread to wait for */ void * *ppStatus /* exit status of thread (out) */ )
This routine will block the calling thread until the thread specified by thread terminates, or is canceled. The thread must be in the joinable state, i.e. it cannot have been detached by a call to pthread_detach( ), or created in the detached state.
If ppStatus is not NULL, when thread terminates its exit status will be stored in the specified location. The exit status will be either the value passed to pthread_exit( ), or PTHREAD_CANCELED if the thread was canceled.
Only one thread can wait for the termination of a given thread. If another thread is already waiting when this function is called an error will be returned (EINVAL).
If the calling thread passes its own ID in thread, the call will fail with the error EDEADLK.
All threads that remain joinable at the time they exit should ensure that pthread_join( ) is called on their behalf by another thread to reclaim the resources that they hold.
On success zero; on failure a non-zero error code.
EINVAL, ESRCH, EDEADLK
pthreadLib, pthread_detach( ), pthread_exit( )
pthread_exit( ) - terminate a thread (POSIX)
void pthread_exit ( void * status /* exit status */ )
This function terminates the calling thread. All cleanup handlers that have been set for the calling thread with pthread_cleanup_push( ) are executed in reverse order (the most recently added handler is executed first). Termination functions for thread-specific data are then called for all keys that have non-NULL values associated with them in the calling thread (see pthread_key_create( ) for more details). Finally, execution of the calling thread is stopped.
The status argument is the return value of the thread and can be consulted from another thread using pthread_join( ) unless this thread was detached (i.e. a call to pthread_detach( ) had been made for it, or it was created in the detached state).
All threads that remain joinable at the time they exit should ensure that pthread_join( ) is called on their behalf by another thread to reclaim the resources that they hold.
Does not return.
N/A
pthreadLib, pthread_cleanup_push( ), pthread_detach( ), pthread_join( ), pthread_key_create( )
pthread_equal( ) - compare thread IDs (POSIX)
int pthread_equal ( pthread_t t1, /* thread one */ pthread_t t2 /* thread two */ )
Tests the equality of the two threads t1 and t2.
Non-zero if t1 and t2 refer to the same thread, otherwise zero.
pthread_self( ) - get the calling thread's ID (POSIX)
pthread_t pthread_self (void)
This function returns the calling thread's ID.
Calling thread's ID.
pthread_once( ) - dynamic package initialization (POSIX)
int pthread_once ( pthread_once_t * onceControl, /* once control location */ void (* initFunc)(void) /* function to call */ )
This routine provides a mechanism to ensure that one, and only one call to a user specified initialization function will occur. This allows all threads in a system to attempt initialization of some feature they need to use, without any need for the application to explicitly prevent multiple calls.
When a thread makes a call to pthread_once( ), the first thread to call it with the specified control variable, onceControl, will result in a call to initFunc, but subsequent calls will not. The onceControl parameter determines whether the associated initialization routine has been called. The initFunc function is complete when pthread_once( ) returns.
The function pthread_once( ) is not a cancellation point; however, if the function initFunc is a cancellation point, and the thread is canceled while executing it, the effect on onceControl is the same as if pthread_once( ) had never been called.
If onceControl has automatic storage duration or is not initialized to the value PTHREAD_ONCE_INIT, the behavior of pthread_once( ) is undefined.
The constant PTHREAD_ONCE_INIT is defined in the pthread.h header file.
Always returns zero.
None.
pthread_key_create( ) - create a thread specific data key (POSIX)
int pthread_key_create ( pthread_key_t * pKey, /* thread specific data key */ void (* destructor)(void * )/* destructor function */ )
This routine allocates a new thread specific data key. The key is stored in the location pointed to by key. The value initially associated with the returned key is NULL in all currently executing threads. If the maximum number of keys are already allocated, the function returns an error (EAGAIN).
The destructor parameter specifies a destructor function associated with the key. When a thread terminates via pthread_exit( ), or by cancellation, destructor is called with the value associated with the key in that thread as an argument. The destructor function is not called if that value is NULL. The order in which destructor functions are called at thread termination time is unspecified.
On success zero; on failure a non-zero error code.
EAGAIN
pthreadLib, pthread_getspecific( ), pthread_key_delete( ), pthread_setspecific( )
pthread_setspecific( ) - set thread specific data (POSIX)
int pthread_setspecific ( pthread_key_t key, /* thread specific data key */ const void * value /* new value */ )
Sets the value of the thread specific data associated with key to value for the calling thread.
On success zero; on failure a non-zero error code.
EINVAL, ENOMEM
pthreadLib, pthread_getspecific( ), pthread_key_create( ), pthread_key_delete( )
pthread_getspecific( ) - get thread specific data (POSIX)
void *pthread_getspecific ( pthread_key_t key /* thread specific data key */ )
This routine returns the value associated with the thread specific data key key for the calling thread.
The value associated with key, or NULL.
N/A
pthreadLib, pthread_key_create( ), pthread_key_delete( ), pthread_setspecific( )
pthread_key_delete( ) - delete a thread specific data key (POSIX)
int pthread_key_delete ( pthread_key_t key /* thread specific data key to delete */ )
This routine deletes the thread specific data associated with key, and deallocates the key itself. It does not call any destructor associated with the key.
On success zero; on failure a non-zero error code.
EINVAL
pthreadLib, pthread_key_create( )
pthread_cancel( ) - cancel execution of a thread (POSIX)
int pthread_cancel ( pthread_t thread /* thread to cancel */ )
This routine sends a cancellation request to the thread specified by thread. Depending on the settings of that thread, it may ignore the request, terminate immediately or defer termination until it reaches a cancellation point.
When the thread terminates it performs as if pthread_exit( ) had been called with the exit status PTHREAD_CANCELED.
In VxWorks, asynchronous thread cancellation is accomplished using a signal. The signal SIGCNCL has been reserved for this purpose. Applications should take care not to block or handle this signal.
On success zero; on failure a non-zero error code.
ESRCH
pthreadLib, pthread_exit( ), pthread_setcancelstate( ), pthread_setcanceltype( ), pthread_testcancel( )
pthread_setcancelstate( ) - set cancellation state for calling thread (POSIX)
int pthread_setcancelstate ( int state, /* new state */ int * oldstate /* old state (out) */ )
This routine sets the cancellation state for the calling thread to state, and, if oldstate is not NULL, returns the old state in the location pointed to by oldstate.
The state can be one of the following:
- PTHREAD_CANCEL_ENABLE
- Enable thread cancellation.
- PTHREAD_CANCEL_DISABLE
- Disable thread cancellation (i.e. thread cancellation requests are ignored).
On success zero; on failure a non-zero error code.
EINVAL
pthreadLib, pthread_cancel( ), pthread_setcanceltype( ), pthread_testcancel( )
pthread_setcanceltype( ) - set cancellation type for calling thread (POSIX)
int pthread_setcanceltype ( int type, /* new type */ int * oldtype /* old type (out) */ )
This routine sets the cancellation type for the calling thread to type. If oldtype is not NULL, then the old cancellation type is stored in the location pointed to by oldtype.
Possible values for type are:
- PTHREAD_CANCEL_ASYNCHRONOUS
- Any cancellation request received by this thread will be acted upon as soon as it is received.
- PTHREAD_CANCEL_DEFERRED
- Cancellation requests received by this thread will be deferred until the next cancellation point is reached.
On success zero; on failure a non-zero error code.
EINVAL
pthreadLib, pthread_cancel( ), pthread_setcancelstate( ), pthread_testcancel( )
pthread_testcancel( ) - create a cancellation point in the calling thread (POSIX)
void pthread_testcancel (void)
This routine creates a cancellation point in the calling thread. It has no effect if cancellation is disabled (i.e. the cancellation state has been set to PTHREAD_CANCEL_DISABLE using the pthread_setcancelstate( ) function).
If cancellation is enabled, the cancellation type is PTHREAD_CANCEL_DEFERRED and a cancellation request has been received, then this routine will call pthread_exit( ) with the exit status set to PTHREAD_CANCELED. If any of these conditions is not met, then the routine does nothing.
N/A
N/A
pthreadLib, pthread_cancel( ), pthread_setcancelstate( ), pthread_setcanceltype( )
pthread_cleanup_push( ) - pushes a routine onto the cleanup stack (POSIX)
void pthread_cleanup_push ( void (* routine)(void * ),/* cleanup routine */ void * arg /* argument */ )
This routine pushes the specified cancellation cleanup handler routine, routine, onto the cancellation cleanup stack of the calling thread. When a thread exits and its cancellation cleanup stack is not empty, the cleanup handlers are invoked with the argument arg in LIFO order from the cancellation cleanup stack.
N/A
N/A
pthreadLib, pthread_cleanup_pop( ), pthread_exit( )
pthread_cleanup_pop( ) - pop a cleanup routine off the top of the stack (POSIX)
void pthread_cleanup_pop ( int run /* execute handler? */ )
This routine removes the cleanup handler routine at the top of the cancellation cleanup stack of the calling thread and executes it if run is non-zero. The routine should have been added using the pthread_cleanup_push( ) function.
Once the routine is removed from the stack it will no longer be called when the thread exits.
N/A
N/A