PORTABILITYISSUES manual page

From 7523c7c4d75652f67cd31cb123e1268790394c8b Mon Sep 17 00:00:00 2001 From: rpj Date: Fri, 6 May 2005 07:27:10 +0000 Subject: '' --- ANNOUNCE | 11 +- ChangeLog | 36 ++ NEWS | 43 ++ create.c | 22 +- implement.h | 89 +++- manual/ChangeLog | 62 +++ manual/PortabilityIssues.html | 718 +++++++++++++++++++++++++++++ manual/index.html | 146 ++++++ manual/pthreadCancelableWait.html | 86 ++++ manual/pthread_attr_init.html | 280 +++++++++++ manual/pthread_attr_setstackaddr.html | 158 +++++++ manual/pthread_attr_setstacksize.html | 127 +++++ manual/pthread_barrier_init.html | 187 ++++++++ manual/pthread_barrier_wait.html | 152 ++++++ manual/pthread_barrierattr_init.html | 142 ++++++ manual/pthread_barrierattr_setpshared.html | 159 +++++++ manual/pthread_cancel.html | 205 ++++++++ manual/pthread_cleanup_push.html | 140 ++++++ manual/pthread_cond_init.html | 313 +++++++++++++ manual/pthread_condattr_init.html | 98 ++++ manual/pthread_condattr_setpshared.html | 153 ++++++ manual/pthread_create.html | 94 ++++ manual/pthread_delay_np.html | 71 +++ manual/pthread_detach.html | 86 ++++ manual/pthread_equal.html | 48 ++ manual/pthread_exit.html | 59 +++ manual/pthread_getw32threadhandle_np.html | 57 +++ manual/pthread_join.html | 118 +++++ manual/pthread_key_create.html | 197 ++++++++ manual/pthread_kill.html | 152 ++++++ manual/pthread_mutex_init.html | 277 +++++++++++ manual/pthread_mutexattr_init.html | 157 +++++++ manual/pthread_mutexattr_setpshared.html | 151 ++++++ manual/pthread_num_processors_np.html | 57 +++ manual/pthread_once.html | 87 ++++ manual/pthread_rwlock_init.html | 193 ++++++++ manual/pthread_rwlock_rdlock.html | 168 +++++++ manual/pthread_rwlock_timedrdlock.html | 156 +++++++ manual/pthread_rwlock_timedwrlock.html | 150 ++++++ manual/pthread_rwlock_unlock.html | 141 ++++++ manual/pthread_rwlock_wrlock.html | 153 ++++++ manual/pthread_rwlockattr_init.html | 141 ++++++ manual/pthread_rwlockattr_setpshared.html | 160 +++++++ manual/pthread_self.html | 70 +++ manual/pthread_setcancelstate.html | 207 +++++++++ manual/pthread_setcanceltype.html | 207 +++++++++ manual/pthread_setconcurrency.html | 155 +++++++ manual/pthread_setschedparam.html | 115 +++++ manual/pthread_spin_init.html | 176 +++++++ manual/pthread_spin_lock.html | 141 ++++++ manual/pthread_spin_unlock.html | 124 +++++ manual/pthread_timechange_handler_np.html | 76 +++ manual/pthread_win32_attach_detach_np.html | 74 +++ manual/pthread_win32_test_features_np.html | 72 +++ manual/sched_get_priority_max.html | 118 +++++ manual/sched_getscheduler.html | 127 +++++ manual/sched_setscheduler.html | 181 ++++++++ manual/sched_yield.html | 98 ++++ manual/sem_init.html | 202 ++++++++ pthread.h | 4 +- pthread_key_create.c | 2 +- pthread_key_delete.c | 33 +- pthread_setspecific.c | 69 +-- ptw32_callUserDestroyRoutines.c | 115 ++--- ptw32_tkAssocCreate.c | 60 +-- ptw32_tkAssocDestroy.c | 41 +- sem_init.c | 7 +- sem_post.c | 27 +- sem_post_multiple.c | 46 +- signal.c | 2 + tests/Bmakefile | 15 +- tests/GNUmakefile | 32 +- tests/Makefile | 76 ++- tests/cancel4.c | 4 +- tests/condvar2.c | 2 +- tests/semaphore1.c | 4 +- tests/stress1.c | 271 +++++++++++ tests/test.h | 18 +- tests/tsd1.c | 38 +- 79 files changed, 8933 insertions(+), 276 deletions(-) create mode 100644 manual/ChangeLog create mode 100644 manual/PortabilityIssues.html create mode 100644 manual/index.html create mode 100644 manual/pthreadCancelableWait.html create mode 100644 manual/pthread_attr_init.html create mode 100644 manual/pthread_attr_setstackaddr.html create mode 100644 manual/pthread_attr_setstacksize.html create mode 100644 manual/pthread_barrier_init.html create mode 100644 manual/pthread_barrier_wait.html create mode 100644 manual/pthread_barrierattr_init.html create mode 100644 manual/pthread_barrierattr_setpshared.html create mode 100644 manual/pthread_cancel.html create mode 100644 manual/pthread_cleanup_push.html create mode 100644 manual/pthread_cond_init.html create mode 100644 manual/pthread_condattr_init.html create mode 100644 manual/pthread_condattr_setpshared.html create mode 100644 manual/pthread_create.html create mode 100644 manual/pthread_delay_np.html create mode 100644 manual/pthread_detach.html create mode 100644 manual/pthread_equal.html create mode 100644 manual/pthread_exit.html create mode 100644 manual/pthread_getw32threadhandle_np.html create mode 100644 manual/pthread_join.html create mode 100644 manual/pthread_key_create.html create mode 100644 manual/pthread_kill.html create mode 100644 manual/pthread_mutex_init.html create mode 100644 manual/pthread_mutexattr_init.html create mode 100644 manual/pthread_mutexattr_setpshared.html create mode 100644 manual/pthread_num_processors_np.html create mode 100644 manual/pthread_once.html create mode 100644 manual/pthread_rwlock_init.html create mode 100644 manual/pthread_rwlock_rdlock.html create mode 100644 manual/pthread_rwlock_timedrdlock.html create mode 100644 manual/pthread_rwlock_timedwrlock.html create mode 100644 manual/pthread_rwlock_unlock.html create mode 100644 manual/pthread_rwlock_wrlock.html create mode 100644 manual/pthread_rwlockattr_init.html create mode 100644 manual/pthread_rwlockattr_setpshared.html create mode 100644 manual/pthread_self.html create mode 100644 manual/pthread_setcancelstate.html create mode 100644 manual/pthread_setcanceltype.html create mode 100644 manual/pthread_setconcurrency.html create mode 100644 manual/pthread_setschedparam.html create mode 100644 manual/pthread_spin_init.html create mode 100644 manual/pthread_spin_lock.html create mode 100644 manual/pthread_spin_unlock.html create mode 100644 manual/pthread_timechange_handler_np.html create mode 100644 manual/pthread_win32_attach_detach_np.html create mode 100644 manual/pthread_win32_test_features_np.html create mode 100644 manual/sched_get_priority_max.html create mode 100644 manual/sched_getscheduler.html create mode 100644 manual/sched_setscheduler.html create mode 100644 manual/sched_yield.html create mode 100644 manual/sem_init.html create mode 100644 tests/stress1.c diff --git a/ANNOUNCE b/ANNOUNCE index 22e786e..6db7c41 100644 --- a/ANNOUNCE +++ b/ANNOUNCE @@ -1,5 +1,5 @@ - PTHREADS-WIN32 RELEASE 1.8.0 (2005-04-26) - ------------------------------------------- + PTHREADS-WIN32 RELEASE 1.9.0 (2005-05-06) + ----------------------------------------- Web Site: http://sources.redhat.com/pthreads-win32/ FTP Site: ftp://sources.redhat.com/pub/pthreads-win32 Maintainer: Ross Johnson @@ -40,6 +40,13 @@ Aurelio Medina and improved by Alexander Terekhov. Many others have contributed significant time and effort to solve crutial problems in order to make the library workable, robust and reliable. +Thanks to Xavier Leroy for granting permission to use and modify his +LinuxThreads manual pages. + +Thanks to The Open Group for making the Single Unix Specification +publicly available - many of the manual pages included in the package +were extracted from it. + There is also a separate CONTRIBUTORS file. This file and others are on the web site: diff --git a/ChangeLog b/ChangeLog index d812aa5..b1ae8c3 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,39 @@ +2005-05-06 Ross Johnson + + * signal.c (sigwait): Add a cancellation point to this otherwise + no-op. + * sem_init.c (sem_init): Check for and return ERANGE error. + * sem_post.c (sem_post): Likewise. + * sem_post_multiple.c (sem_post_multiple): Likewise. + * manual (directory): Added; see ChangeLog inside. + +2005-05-02 Ross Johnson + + * implement.h (struct pthread_key_t_): Change threadsLock to keyLock + so as not to be confused with the per thread lock 'threadlock'; + change all references to it. + * implement.h (struct ThreadKeyAssoc): Remove lock; add prevKey + and prevThread pointers; re-implemented all routines that use this + struct. The effect of this is to save one handle per association, + which could potentially equal the number of keys multiplied by the + number of threads, accumulating over time - and to free the + association memory as soon as it is no longer referenced by either + the key or the thread. Previously, the handle and memory were + released only after BOTH key and thread no longer referenced the + association. That is, often no association resources were released + until the process itself exited. In addition, at least one race + condition has been removed - where two threads could attempt to + release the association resources simultaneously - one via + ptw32_callUserDestroyRoutines and the other via + pthread_key_delete. + - thanks to Richard Hughes at Aculab for discovering the problem. + * pthread_key_create.c: See above. + * pthread_key_delete.c: See above. + * pthread_setspecific.c: See above. + * ptw32_callUserDestroyRoutines.c: See above. + * ptw32_tkAssocCreate.c: See above. + * ptw32_tkAssocDestroy.c: See above. + 2005-04-27 Ross Johnson * sem_wait.c (ptw32_sem_wait_cleanup): after cancellation re-attempt diff --git a/NEWS b/NEWS index 22f4bcf..a4b3809 100644 --- a/NEWS +++ b/NEWS @@ -1,3 +1,46 @@ +RELEASE 1.9.0 +------------- +(2005-05-06) + +General +------- + +All of the bug fixes and new features in this release have been +back-ported from release 2.5.0. + +The package now includes a reference documentation set consisting of +HTML formatted Unix-style manual pages that have been edited for +consistency with Pthreads-w32. The set can also be read online at: +http://sources.redhat.com/pthreads-win32/manual/index.html + +Bugs fixed +---------- + +* Thread Specific Data (TSD) key management has been altered to +eliminate a source of resource leakage (HANDLEs plus memory). +Thanks to Richard Hughes at Aculab for identifying the leak. + +* Fix a semaphore accounting race between sem_post/sem_post_multiple +and sem_wait cancellation. This is the same issue as with +sem_timedwait that was fixed in the last release. + +* sem_init, sem_post, and sem_post_multiple now check that the +semaphore count never exceeds _POSIX_SEM_VALUE_MAX. + +* Although sigwait() is nothing more than a no-op, it should at least +be a cancellation point to be consistent with the standard. + +New tests +--------- + +* stress1.c - attempts to expose problems in condition variable +and semaphore timed wait logic. This test was inspired by Stephan +Mueller's sample test code used to identify the sem_timedwait bug +from the last release. It's not a part of the regular test suite +because it can take awhile to run. To run it: +nmake clean VC-stress + + RELEASE 1.8.0 ------------- (2005-04-26) diff --git a/create.c b/create.c index 919db2e..9e9388b 100644 --- a/create.c +++ b/create.c @@ -92,6 +92,7 @@ pthread_create (pthread_t * tid, ThreadParms *parms = NULL; long stackSize; int priority; + pthread_t self; /* * Before doing anything, check that tid can be stored through @@ -128,18 +129,23 @@ pthread_create (pthread_t * tid, parms->start = start; parms->arg = arg; +#if defined(HAVE_SIGSET_T) + + /* + * Threads inherit their initial sigmask from their creator thread. + */ + self = pthread_self(); + tp->sigmask = ((ptw32_thread_t *)self.p)->sigmask; + +#endif /* HAVE_SIGSET_T */ + + if (a != NULL) { stackSize = a->stacksize; tp->detachState = a->detachstate; priority = a->param.sched_priority; -#if HAVE_SIGSET_T - - tp->sigmask = a->sigmask; - -#endif /* HAVE_SIGSET_T */ - #if (THREAD_PRIORITY_LOWEST > THREAD_PRIORITY_NORMAL) /* WinCE */ #else @@ -164,7 +170,9 @@ pthread_create (pthread_t * tid, * then the inherited priority could be the result of a temporary * system adjustment. This is not the case for POSIX threads. */ - pthread_t self = pthread_self (); +#if ! defined(HAVE_SIGSET_T) + self = pthread_self (); +#endif priority = ((ptw32_thread_t *) self.p)->sched_priority; } diff --git a/implement.h b/implement.h index d575539..994a768 100644 --- a/implement.h +++ b/implement.h @@ -266,7 +266,7 @@ struct pthread_key_t_ { DWORD key; void (*destructor) (void *); - pthread_mutex_t threadsLock; + pthread_mutex_t keyLock; void *threads; }; @@ -347,26 +347,67 @@ struct ThreadKeyAssoc { /* * Purpose: - * This structure creates an association between a - * thread and a key. - * It is used to implement the implicit invocation - * of a user defined destroy routine for thread - * specific data registered by a user upon exiting a - * thread. + * This structure creates an association between a thread and a key. + * It is used to implement the implicit invocation of a user defined + * destroy routine for thread specific data registered by a user upon + * exiting a thread. * - * Attributes: - * lock - * protects access to the rest of the structure + * Graphically, the arrangement is as follows, where: + * + * K - Key with destructor + * (head of chain is key->threads) + * T - Thread that has called pthread_setspecific(Kn) + * (head of chain is thread->keys) + * A - Association. Each association is a node at the + * intersection of two doubly-linked lists. + * + * T1 T2 T3 + * | | | + * | | | + * K1 -----+-----A-----A-----> + * | | | + * | | | + * K2 -----A-----A-----+-----> + * | | | + * | | | + * K3 -----A-----+-----A-----> + * | | | + * | | | + * V V V + * + * Access to the association is guarded by two locks: the key's + * general lock (guarding the row) and the thread's general + * lock (guarding the column). This avoids the need for a + * dedicated lock for each association, which not only consumes + * more handles but requires that: before the lock handle can + * be released - both the key must be deleted and the thread + * must have called the destructor. The two-lock arrangement + * allows the resources to be freed as soon as either thread or + * key is concluded. + * + * To avoid deadlock: whenever both locks are required, the key + * and thread locks are always applied in the order: key lock + * then thread lock. * + * An association is created when a thread first calls + * pthread_setspecific() on a key that has a specified + * destructor. + * + * An association is destroyed either immediately after the + * thread calls the key destructor function on thread exit, or + * when the key is deleted. + * + * Attributes: * thread - * reference to the thread that owns the association. - * As long as this is not NULL, the association remains - * referenced by the pthread_t. + * reference to the thread that owns the + * association. This is actually the pointer to the + * thread struct itself. Since the association is + * destroyed before the thread exits, this can never + * point to a different logical thread to the one that + * created the assoc, i.e. after thread struct reuse. * * key * reference to the key that owns the association. - * As long as this is not NULL, the association remains - * referenced by the pthread_key_t. * * nextKey * The pthread_t->keys attribute is the head of a @@ -375,6 +416,9 @@ struct ThreadKeyAssoc * between a pthread_t and all pthread_key_t on which * it called pthread_setspecific. * + * prevKey + * Similarly. + * * nextThread * The pthread_key_t->threads attribute is the head of * a chain of assoctiations that runs through the @@ -383,11 +427,13 @@ struct ThreadKeyAssoc * PThreads that have called pthread_setspecific for * this pthread_key_t. * + * prevThread + * Similarly. * * Notes: - * 1) As long as one of the attributes, thread or key, is - * not NULL, the association is being referenced; once - * both are NULL, the association must be released. + * 1) As soon as either the key or the thread is no longer + * referencing the association, it can be destroyed. The + * association will be removed from both chains. * * 2) Under WIN32, an association is only created by * pthread_setspecific if the user provided a @@ -395,11 +441,12 @@ struct ThreadKeyAssoc * * */ - pthread_mutex_t lock; - pthread_t thread; + ptw32_thread_t * thread; pthread_key_t key; ThreadKeyAssoc *nextKey; ThreadKeyAssoc *nextThread; + ThreadKeyAssoc *prevKey; + ThreadKeyAssoc *prevThread; }; @@ -564,7 +611,7 @@ extern "C" void ptw32_callUserDestroyRoutines (pthread_t thread); int ptw32_tkAssocCreate (ThreadKeyAssoc ** assocP, - pthread_t thread, pthread_key_t key); + ptw32_thread_t * thread, pthread_key_t key); void ptw32_tkAssocDestroy (ThreadKeyAssoc * assoc); diff --git a/manual/ChangeLog b/manual/ChangeLog new file mode 100644 index 0000000..c07cdd7 --- /dev/null +++ b/manual/ChangeLog @@ -0,0 +1,62 @@ +2005-05-06 Ross Johnson + + * PortabilityIssues.html: Was nonPortableIssues.html. + * index.html: Updated; add table of contents at top. + * *.html: Add Pthreads-win32 header info; add link back to the + index page 'index.html'. + +2005-05-06 Ross Johnson + + * index.html: New. + * nonPortableIssues.html: New. + * pthread_attr_init.html: New. + * pthread_attr_setstackaddr.html: New. + * pthread_attr_setstacksize.html: New. + * pthread_barrierattr_init.html: New. + * pthread_barrierattr_setpshared.html: New. + * pthread_barrier_init.html: New. + * pthread_barrier_wait.html: New. + * pthreadCancelableWait.html: New. + * pthread_cancel.html: New. + * pthread_cleanup_push.html: New. + * pthread_condattr_init.html: New. + * pthread_condattr_setpshared.html: New. + * pthread_cond_init.html: New. + * pthread_create.html: New. + * pthread_delay_np.html: New. + * pthread_detach.html: New. + * pthread_equal.html: New. + * pthread_exit.html: New. + * pthread_getw32threadhandle_np.html: New. + * pthread_join.html: New. + * pthread_key_create.html: New. + * pthread_kill.html: New. + * pthread_mutexattr_init.html: New. + * pthread_mutexattr_setpshared.html: New. + * pthread_mutex_init.html: New. + * pthread_num_processors_np.html: New. + * pthread_once.html: New. + * pthread_rwlockattr_init.html: New. + * pthread_rwlockattr_setpshared.html: New. + * pthread_rwlock_init.html: New. + * pthread_rwlock_rdlock.html: New. + * pthread_rwlock_timedrdlock.html: New. + * pthread_rwlock_timedwrlock.html: New. + * pthread_rwlock_unlock.html: New. + * pthread_rwlock_wrlock.html: New. + * pthread_self.html: New. + * pthread_setcancelstate.html: New. + * pthread_setcanceltype.html: New. + * pthread_setconcurrency.html: New. + * pthread_setschedparam.html: New. + * pthread_spin_init.html: New. + * pthread_spin_lock.html: New. + * pthread_spin_unlock.html: New. + * pthread_timechange_handler_np.html: New. + * pthread_win32_attach_detach_np.html: New. + * pthread_win32_test_features_np.html: New. + * sched_get_priority_max.html: New. + * sched_getscheduler.html: New. + * sched_setscheduler.html: New. + * sched_yield.html: New. + * sem_init.html: New. diff --git a/manual/PortabilityIssues.html b/manual/PortabilityIssues.html new file mode 100644 index 0000000..376a5f0 --- /dev/null +++ b/manual/PortabilityIssues.html @@ -0,0 +1,718 @@ + + + + + PORTABILITYISSUES manual page + + + + + +

POSIX Threads for Windows – REFERENCE - Pthreads-w32

Reference Index

Name

Portability issues

Synopsis

Thread priority

Description

Thread priority

POSIX defines a single contiguous range +of numbers that determine a thread's priority. Win32 defines priority +classes - and priority levels relative to these classes. Classes are +simply priority base levels that the defined priority levels are +relative to such that, changing a process's priority class will +change the priority of all of it's threads, while the threads retain +the same relativity to each other.

A Win32 system defines a single +contiguous monotonic range of values that define system priority +levels, just like POSIX. However, Win32 restricts individual threads +to a subset of this range on a per-process basis.

The following table shows the base +priority levels for combinations of priority class and priority value +in Win32.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

+ + +	+ Process Priority Class +	+ Thread Priority Level +
+ 1 +	+ IDLE_PRIORITY_CLASS +	+ THREAD_PRIORITY_IDLE +
+ 1 +	+ BELOW_NORMAL_PRIORITY_CLASS +	+ THREAD_PRIORITY_IDLE +
+ 1 +	+ NORMAL_PRIORITY_CLASS +	+ THREAD_PRIORITY_IDLE +
+ 1 +	+ ABOVE_NORMAL_PRIORITY_CLASS +	+ THREAD_PRIORITY_IDLE +
+ 1 +	+ HIGH_PRIORITY_CLASS +	+ THREAD_PRIORITY_IDLE +
+ 2 +	+ IDLE_PRIORITY_CLASS +	+ THREAD_PRIORITY_LOWEST +
+ 3 +	+ IDLE_PRIORITY_CLASS +	+ THREAD_PRIORITY_BELOW_NORMAL +
+ 4 +	+ IDLE_PRIORITY_CLASS +	+ THREAD_PRIORITY_NORMAL +
+ 4 +	+ BELOW_NORMAL_PRIORITY_CLASS +	+ THREAD_PRIORITY_LOWEST +
+ 5 +	+ IDLE_PRIORITY_CLASS +	+ THREAD_PRIORITY_ABOVE_NORMAL +
+ 5 +	+ BELOW_NORMAL_PRIORITY_CLASS +	+ THREAD_PRIORITY_BELOW_NORMAL +
+ 5 +	+ Background NORMAL_PRIORITY_CLASS +	+ THREAD_PRIORITY_LOWEST +
+ 6 +	+ IDLE_PRIORITY_CLASS +	+ THREAD_PRIORITY_HIGHEST +
+ 6 +	+ BELOW_NORMAL_PRIORITY_CLASS +	+ THREAD_PRIORITY_NORMAL +
+ 6 +	+ Background NORMAL_PRIORITY_CLASS +	+ THREAD_PRIORITY_BELOW_NORMAL +
+ 7 +	+ BELOW_NORMAL_PRIORITY_CLASS +	+ THREAD_PRIORITY_ABOVE_NORMAL +
+ 7 +	+ Background NORMAL_PRIORITY_CLASS +	+ THREAD_PRIORITY_NORMAL +
+ 7 +	+ Foreground NORMAL_PRIORITY_CLASS +	+ THREAD_PRIORITY_LOWEST +
+ 8 +	+ BELOW_NORMAL_PRIORITY_CLASS +	+ THREAD_PRIORITY_HIGHEST +
+ 8 +	+ NORMAL_PRIORITY_CLASS +	+ THREAD_PRIORITY_ABOVE_NORMAL +
+ 8 +	+ Foreground NORMAL_PRIORITY_CLASS +	+ THREAD_PRIORITY_BELOW_NORMAL +
+ 8 +	+ ABOVE_NORMAL_PRIORITY_CLASS +	+ THREAD_PRIORITY_LOWEST +
+ 9 +	+ NORMAL_PRIORITY_CLASS +	+ THREAD_PRIORITY_HIGHEST +
+ 9 +	+ Foreground NORMAL_PRIORITY_CLASS +	+ THREAD_PRIORITY_NORMAL +
+ 9 +	+ ABOVE_NORMAL_PRIORITY_CLASS +	+ THREAD_PRIORITY_BELOW_NORMAL +
+ 10 +	+ Foreground NORMAL_PRIORITY_CLASS +	+ THREAD_PRIORITY_ABOVE_NORMAL +
+ 10 +	+ ABOVE_NORMAL_PRIORITY_CLASS +	+ THREAD_PRIORITY_NORMAL +
+ 11 +	+ Foreground NORMAL_PRIORITY_CLASS +	+ THREAD_PRIORITY_HIGHEST +
+ 11 +	+ ABOVE_NORMAL_PRIORITY_CLASS +	+ THREAD_PRIORITY_ABOVE_NORMAL +
+ 11 +	+ HIGH_PRIORITY_CLASS +	+ THREAD_PRIORITY_LOWEST +
+ 12 +	+ ABOVE_NORMAL_PRIORITY_CLASS +	+ THREAD_PRIORITY_HIGHEST +
+ 12 +	+ HIGH_PRIORITY_CLASS +	+ THREAD_PRIORITY_BELOW_NORMAL +
+ 13 +	+ HIGH_PRIORITY_CLASS +	+ THREAD_PRIORITY_NORMAL +
+ 14 +	+ HIGH_PRIORITY_CLASS +	+ THREAD_PRIORITY_ABOVE_NORMAL +
+ 15 +	+ HIGH_PRIORITY_CLASS +	+ THREAD_PRIORITY_HIGHEST +
+ 15 +	+ HIGH_PRIORITY_CLASS +	+ THREAD_PRIORITY_TIME_CRITICAL +
+ 15 +	+ IDLE_PRIORITY_CLASS +	+ THREAD_PRIORITY_TIME_CRITICAL +
+ 15 +	+ BELOW_NORMAL_PRIORITY_CLASS +	+ THREAD_PRIORITY_TIME_CRITICAL +
+ 15 +	+ NORMAL_PRIORITY_CLASS +	+ THREAD_PRIORITY_TIME_CRITICAL +
+ 15 +	+ ABOVE_NORMAL_PRIORITY_CLASS +	+ THREAD_PRIORITY_TIME_CRITICAL +
+ 16 +	+ REALTIME_PRIORITY_CLASS +	+ THREAD_PRIORITY_IDLE +
+ 17 +	+ REALTIME_PRIORITY_CLASS +	+ -7 +
+ 18 +	+ REALTIME_PRIORITY_CLASS +	+ -6 +
+ 19 +	+ REALTIME_PRIORITY_CLASS +	+ -5 +
+ 20 +	+ REALTIME_PRIORITY_CLASS +	+ -4 +
+ 21 +	+ REALTIME_PRIORITY_CLASS +	+ -3 +
+ 22 +	+ REALTIME_PRIORITY_CLASS +	+ THREAD_PRIORITY_LOWEST +
+ 23 +	+ REALTIME_PRIORITY_CLASS +	+ THREAD_PRIORITY_BELOW_NORMAL +
+ 24 +	+ REALTIME_PRIORITY_CLASS +	+ THREAD_PRIORITY_NORMAL +
+ 25 +	+ REALTIME_PRIORITY_CLASS +	+ THREAD_PRIORITY_ABOVE_NORMAL +
+ 26 +	+ REALTIME_PRIORITY_CLASS +	+ THREAD_PRIORITY_HIGHEST +
+ 27 +	+ REALTIME_PRIORITY_CLASS +	+ 3 +
+ 28 +	+ REALTIME_PRIORITY_CLASS +	+ 4 +
+ 29 +	+ REALTIME_PRIORITY_CLASS +	+ 5 +
+ 30 +	+ REALTIME_PRIORITY_CLASS +	+ 6 +
+ 31 +	+ REALTIME_PRIORITY_CLASS +	+ THREAD_PRIORITY_TIME_CRITICAL +

+ +

Windows NT: Values -7, -6, -5, -4, -3, 3, +4, 5, and 6 are not supported.

As you can see, the real priority levels +available to any individual Win32 thread are non-contiguous.

An application using Pthreads-w32 should +not make assumptions about the numbers used to represent thread +priority levels, except that they are monotonic between the values +returned by sched_get_priority_min() and sched_get_priority_max(). +E.g. Windows 95, 98, NT, 2000, XP make available a non-contiguous +range of numbers between -15 and 15, while at least one version of +WinCE (3.0) defines the minimum priority (THREAD_PRIORITY_LOWEST) as +5, and the maximum priority (THREAD_PRIORITY_HIGHEST) as 1.

Internally, pthreads-win32 maps any +priority levels between THREAD_PRIORITY_IDLE and +THREAD_PRIORITY_LOWEST to THREAD_PRIORITY_LOWEST, or between +THREAD_PRIORITY_TIME_CRITICAL and THREAD_PRIORITY_HIGHEST to +THREAD_PRIORITY_HIGHEST. Currently, this also applies to +REALTIME_PRIORITY_CLASS even if levels -7, -6, -5, -4, -3, 3, 4, 5, +and 6 are supported.

If it wishes, a Win32 application using +pthreads-w32 can use the Win32 defined priority macros +THREAD_PRIORITY_IDLE through THREAD_PRIORITY_TIME_CRITICAL.

Author

Ross Johnson for use with Pthreads-w32.

POSIX threads API reference

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_init

pthread_attr_setdetachstate

pthread_attr_setinheritsched

pthread_attr_setschedparam

pthread_attr_setschedpolicy

pthread_attr_setscope

pthread_attr_setstackaddr

pthread_attr_setstacksize

pthread_barrierattr_destroy

pthread_barrierattr_getpshared

pthread_barrierattr_init

pthread_barrierattr_setpshared

pthread_barrier_destroy

pthread_barrier_init

pthread_barrier_wait

pthread_cancel

pthread_cleanup_pop

pthread_cleanup_push

pthread_condattr_destroy

pthread_condattr_getpshared

pthread_condattr_init

pthread_condattr_setpshared

pthread_cond_broadcast

pthread_cond_destroy

pthread_cond_init

pthread_cond_signal

pthread_cond_timedwait

pthread_cond_wait

pthread_getconcurrency

pthread_getschedparam

pthread_getspecific

pthread_join

pthread_key_create

pthread_key_delete

pthread_kill

pthread_mutexattr_destroy

pthread_mutexattr_getkind_np

pthread_mutexattr_getpshared

pthread_mutexattr_gettype

pthread_mutexattr_init

pthread_mutexattr_setkind_np

pthread_mutexattr_setpshared

pthread_mutexattr_settype

pthread_mutex_destroy

pthread_mutex_init

pthread_mutex_lock

pthread_mutex_timedlock

pthread_mutex_trylock

pthread_mutex_unlock

pthread_once

pthread_rwlockattr_destroy

pthread_rwlockattr_getpshared

pthread_rwlockattr_init

pthread_rwlockattr_setpshared

pthread_rwlock_destroy

pthread_rwlock_init

pthread_rwlock_rdlock

pthread_rwlock_timedrdlock

pthread_rwlock_timedwrlock

pthread_rwlock_tryrdlock

pthread_rwlock_trywrlock

pthread_rwlock_unlock

pthread_rwlock_wrlock

pthread_self

pthread_setcancelstate

pthread_setcanceltype

pthread_setconcurrency

pthread_setschedparam

pthread_setspecific

pthread_sigmask

pthread_spin_destroy

pthread_spin_init

pthread_spin_lock

pthread_spin_trylock

pthread_spin_unlock

pthread_testcancel

sched_get_priority_max

sched_get_priority_min

sched_getscheduler

sched_setscheduler

sem_close

sem_open

sem_post_multiple

sem_unlink

Miscellaneous POSIX thread safe +routines provided by Pthreads-w32

asctime_r

ctime_r

gmtime_r

localtime_r

rand_r

Non-portable Pthreads-w32 routines

pthreadCancelableTimedWait

pthreadCancelableWait

pthread_delay_np

pthread_getw32threadhandle_np

pthread_num_processors_np

pthread_win32_test_features_np

pthread_timechange_handler_np

pthread_win32_process_attach_np

pthread_win32_process_detach_np

pthread_win32_thread_attach_np

pthread_win32_thread_detach_np

Other

Portability +issues

+ + diff --git a/manual/pthreadCancelableWait.html b/manual/pthreadCancelableWait.html new file mode 100644 index 0000000..9d7c1a4 --- /dev/null +++ b/manual/pthreadCancelableWait.html @@ -0,0 +1,86 @@ + + + + + PTHREADCANCELLABLEWAIT manual page + + + + + + + +

POSIX Threads for Windows – REFERENCE - Pthreads-w32

Reference Index

Table of Contents

Name

pthreadCancelableTimedWait, +pthreadCancelableWait – provide cancellation hooks for user Win32 +routines

Synopsis

#include <pthread.h> +

int pthreadCancelableTimedWait (HANDLE waitHandle, +DWORD timeout);

int pthreadCancelableWait (HANDLE waitHandle);

Description

These two functions provide hooks into the pthread_cancel() +mechanism that will allow you to wait on a Windows handle and make it +a cancellation point. Both functions block until either the given +Win32 HANDLE is signalled, or pthread_cancel() +has been called. They are implemented using WaitForMultipleObjects +on waitHandle and the manually reset Win32 event handle that +is the target of pthread_cancel(). +These routines may be called from Win32 native threads but +pthread_cancel() will +require that thread's POSIX thread ID that the thread must retrieve +using pthread_self().

pthreadCancelableTimedWait is the timed version that will +return with the code ETIMEDOUT if the interval timeout +milliseconds elapses before waitHandle is signalled.

Cancellation

These routines allow routines that block on Win32 HANDLEs to be +cancellable via pthread_cancel().

Return Value

Errors

The pthreadCancelableTimedWait function returns the +following error code on error: +

ETIMEDOUT +

+ +

+The interval timeout milliseconds elapsed before waitHandle +was signalled.

Author

Ross Johnson for use with Pthreads-w32.

Name

pthread_attr_init, pthread_attr_destroy, +pthread_attr_setdetachstate, pthread_attr_getdetachstate, +pthread_attr_setschedparam, pthread_attr_getschedparam, +pthread_attr_setschedpolicy, pthread_attr_getschedpolicy, +pthread_attr_setinheritsched, pthread_attr_getinheritsched, +pthread_attr_setscope, pthread_attr_getscope - thread creation +attributes +

Synopsis

#include <pthread.h> +

int pthread_attr_init(pthread_attr_t *attr); +

int pthread_attr_destroy(pthread_attr_t *attr); +

int pthread_attr_setdetachstate(pthread_attr_t *attr, +int detachstate); +

int pthread_attr_getdetachstate(const pthread_attr_t *attr, +int *detachstate); +

int pthread_attr_setschedpolicy(pthread_attr_t *attr, +int policy); +

int pthread_attr_getschedpolicy(const pthread_attr_t *attr, +int *policy); +

int pthread_attr_setschedparam(pthread_attr_t *attr, +const struct sched_param *param); +

int pthread_attr_getschedparam(const pthread_attr_t *attr, +struct sched_param *param); +

int pthread_attr_setinheritsched(pthread_attr_t *attr, +int inherit); +

int pthread_attr_getinheritsched(const pthread_attr_t *attr, +int *inherit); +

int pthread_attr_setscope(pthread_attr_t *attr, +int scope); +

int pthread_attr_getscope(const pthread_attr_t *attr, +int *scope); +

Description

Setting attributes for threads is achieved by filling a thread +attribute object attr of type pthread_attr_t, then +passing it as second argument to pthread_create(3) +. Passing NULL is equivalent to passing a thread attribute +object with all attributes set to their default values. +

pthread_attr_init initializes the thread attribute object +attr and fills it with default values for the attributes. (The +default values are listed below for each attribute.) +

Each attribute attrname (see below for a list of all +attributes) can be individually set using the function +pthread_attr_setattrname and retrieved using the +function pthread_attr_getattrname. +

pthread_attr_destroy destroys a thread attribute object, +which must not then be reused until it is reinitialized. +

Attribute objects are consulted only when creating a new thread. +The same attribute object can be used for creating several threads. +Modifying an attribute object after a call to pthread_create +does not change the attributes of the thread previously created. +

The following thread attributes are supported: +

detachstate

Control whether the thread is created in the joinable state (value +PTHREAD_CREATE_JOINABLE) or in the detached state ( +PTHREAD_CREATE_DETACHED). +

Default value: PTHREAD_CREATE_JOINABLE. +

In the joinable state, another thread can synchronize on the +thread termination and recover its termination code using +pthread_join(3) . When a +joinable thread terminates, some of the thread resources are kept +allocated, and released only when another thread performs +pthread_join(3) on that +thread. +

In the detached state, the thread's resources are released +immediately when it terminates. pthread_join(3) +cannot be used to synchronize on the thread termination. +

A thread created in the joinable state can later be put in the +detached thread using pthread_detach(3) +. +

schedpolicy

Select the scheduling policy for the thread: one of SCHED_OTHER +(regular, non-real-time scheduling), SCHED_RR (real-time, +round-robin) or SCHED_FIFO (real-time, first-in first-out). +

Pthreads-w32 only supports SCHED_OTHER - attempting +to set one of the other policies will return an error ENOTSUP.

Default value: SCHED_OTHER. +

Pthreads-w32 only supports SCHED_OTHER - attempting +to set one of the other policies will return an error ENOTSUP.

The scheduling policy of a thread can be changed after creation +with pthread_setschedparam(3) +. +

schedparam

Contain the scheduling parameters (essentially, the scheduling +priority) for the thread.

Pthreads-w32 supports the priority levels defined by the +Windows system it is running on. Under Windows, thread priorities are +relative to the process priority class, which must be set via the +Windows W32 API.

Default value: priority is 0 (Win32 level THREAD_PRIORITY_NORMAL). +

The scheduling priority of a thread can be changed after creation +with pthread_setschedparam(3) +. +

inheritsched

Indicate whether the scheduling policy and scheduling parameters +for the newly created thread are determined by the values of the +schedpolicy and schedparam attributes (value +PTHREAD_EXPLICIT_SCHED) or are inherited from the parent +thread (value PTHREAD_INHERIT_SCHED). +

Default value: PTHREAD_EXPLICIT_SCHED. +

scope

Define the scheduling contention scope for the created thread. The +only value supported in the Pthreads-w32 implementation is +PTHREAD_SCOPE_SYSTEM, meaning that the threads contend for CPU +time with all processes running on the machine. The other value +specified by the standard, PTHREAD_SCOPE_PROCESS, means that +scheduling contention occurs only between the threads of the running +process.

Pthreads-w32 only supports PTHREAD_SCOPE_SYSTEM.

Default value: PTHREAD_SCOPE_SYSTEM. +

Return Value

All functions return 0 on success and a non-zero error code on +error. On success, the pthread_attr_getattrname +functions also store the current value of the attribute attrname +in the location pointed to by their second argument. +

Errors

The pthread_attr_setdetachstate function returns the +following error codes on error: +

EINVAL +: + the specified detachstate is not one of + PTHREAD_CREATE_JOINABLE or PTHREAD_CREATE_DETACHED. +

+ +

+The pthread_attr_setschedparam function returns the following +error codes on error: +

EINVAL +: + the priority specified in param is outside the range of + allowed priorities for the scheduling policy currently in attr + (1 to 99 for SCHED_FIFO and SCHED_RR; 0 for + SCHED_OTHER). +

+ +

+The pthread_attr_setschedpolicy function returns the following +error codes on error: +

EINVAL +: + the specified policy is not one of SCHED_OTHER, + SCHED_FIFO, or SCHED_RR. +
+ ENOTSUP +: + policy is not SCHED_OTHER, the only value supported + by Pthreads-w32.

+ +

+The pthread_attr_setinheritsched function returns the +following error codes on error: +

EINVAL +: + the specified inherit is not one of PTHREAD_INHERIT_SCHED + or PTHREAD_EXPLICIT_SCHED. +

+ +

+The pthread_attr_setscope function returns the following error +codes on error: +

EINVAL +: + the specified scope is not one of PTHREAD_SCOPE_SYSTEM + or PTHREAD_SCOPE_PROCESS. +
+ ENOTSUP +: + the specified scope is PTHREAD_SCOPE_PROCESS (not + supported by Pthreads-w32). +

+ +

+Author

Xavier Leroy <Xavier.Leroy@inria.fr> +

Modified by Ross Johnson for use with Pthreads-w32.

Name

pthread_attr_getstackaddr, pthread_attr_setstackaddr - get and set +the stackaddr attribute +

Synopsis

#include <pthread.h> +

int pthread_attr_getstackaddr(const pthread_attr_t *restrict +attr, void **restrict stackaddr);
int +pthread_attr_setstackaddr(pthread_attr_t *attr, void +*stackaddr); +

Description

The pthread_attr_getstackaddr and pthread_attr_setstackaddr +functions, respectively, shall get and set the thread creation +stackaddr attribute in the attr object. +

The stackaddr attribute specifies the location of storage +to be used for the created thread’s stack. The size of the storage +shall be at least {PTHREAD_STACK_MIN}. +

Pthreads-w32 defines _POSIX_THREAD_ATTR_STACKADDR in +pthread.h as -1 to indicate that these routines are implemented but +cannot used to set or get the stack address. These routines always +return the error ENOSYS when called.

Return Value

Upon successful completion, pthread_attr_getstackaddr and +pthread_attr_setstackaddr shall return a value of 0; +otherwise, an error number shall be returned to indicate the error. +

The pthread_attr_getstackaddr function stores the stackaddr +attribute value in stackaddr if successful. +

Errors

The pthread_attr_setstackaddr function always returns the +following error code: +

ENOSYS: + The function is not supported. +

+ +

+The pthread_attr_getstackaddr function always returns the +following error code: +

ENOSYS: + The function is not supported. +

+ +

+These functions shall not return an error code of [EINTR]. +

The following sections are informative. +

Examples

None. +

Application Usage

The specification of the stackaddr attribute presents +several ambiguities that make portable use of these interfaces +impossible. The description of the single address parameter as a +"stack" does not specify a particular relationship between +the address and the "stack" implied by that address. For +example, the address may be taken as the low memory address of a +buffer intended for use as a stack, or it may be taken as the address +to be used as the initial stack pointer register value for the new +thread. These two are not the same except for a machine on which the +stack grows "up" from low memory to high, and on which a +"push" operation first stores the value in memory and then +increments the stack pointer register. Further, on a machine where +the stack grows "down" from high memory to low, +interpretation of the address as the "low memory" address +requires a determination of the intended size of the stack. +IEEE Std 1003.1-2001 has introduced the new interfaces +pthread_attr_setstack(3) +and pthread_attr_getstack(3) +to resolve these ambiguities. +

Rationale

None. +

Future Directions

None. +

Copyright

Portions of this text are reprinted and reproduced in electronic +form from IEEE Std 1003.1, 2003 Edition, Standard for Information +Technology -- Portable Operating System Interface (POSIX), The Open +Group Base Specifications Issue 6, Copyright (C) 2001-2003 by the +Institute of Electrical and Electronics Engineers, Inc and The Open +Group. In the event of any discrepancy between this version and the +original IEEE and The Open Group Standard, the original IEEE and The +Open Group Standard is the referee document. The original Standard +can be obtained online at http://www.opengroup.org/unix/online.html +. +

Modified by Ross Johnson for use with Pthreads-w32.

Table of Contents

Name +
+
Synopsis +
+
Description +
+
Return + Value +
+
Errors +
+
Examples +
+
Application + Usage +
+
Rationale +
+
Future + Directions +
+
See + Also +
+
Copyright +
+

+ + diff --git a/manual/pthread_attr_setstacksize.html b/manual/pthread_attr_setstacksize.html new file mode 100644 index 0000000..ae9d031 --- /dev/null +++ b/manual/pthread_attr_setstacksize.html @@ -0,0 +1,127 @@ + + + + + "PTHREAD_ATTR_GETSTACKSIZE"(P) manual page + + + + + + + +

POSIX Threads for Windows – REFERENCE - Pthreads-w32

Reference Index

Table of Contents

Name

pthread_attr_getstacksize, pthread_attr_setstacksize - get and set +the stacksize attribute +

Synopsis

#include <pthread.h> +

int pthread_attr_getstacksize(const pthread_attr_t *restrict +attr, size_t *restrict stacksize);
int +pthread_attr_setstacksize(pthread_attr_t *attr, size_t +stacksize); +

Description

The pthread_attr_getstacksize and pthread_attr_setstacksize +functions, respectively, shall get and set the thread creation +stacksize attribute in the attr object. +

The stacksize attribute shall define the minimum stack size +(in bytes) allocated for the created threads stack. +

Pthreads-w32 defines _POSIX_THREAD_ATTR_STACKSIZE in +pthread.h to indicate that these routines are implemented and may be +used to set or get the stack size.

Default value: 0 (in Pthreads-w32 a value of 0 means the stack +will grow as required)

Return Value

Upon successful completion, pthread_attr_getstacksize and +pthread_attr_setstacksize shall return a value of 0; +otherwise, an error number shall be returned to indicate the error. +

The pthread_attr_getstacksize function stores the stacksize +attribute value in stacksize if successful. +

Errors

The pthread_attr_setstacksize function shall fail if: +

EINVAL +: + The value of stacksize is less than {PTHREAD_STACK_MIN} or + exceeds a system-imposed limit. +

+These functions shall not return an error code of [EINTR]. +

The following sections are informative. +

Examples

None. +

Application Usage

None. +

Rationale

None. +

Future Directions

None. +

Copyright

Modified by Ross Johnson for use with Pthreads-w32.

Table of Contents

Name +
+
Synopsis +
+
Description +
+
Return + Value +
+
Errors +
+
Examples +
+
Application + Usage +
+
Rationale +
+
Future + Directions +
+
See + Also +
+
Copyright +
+

+ + diff --git a/manual/pthread_barrier_init.html b/manual/pthread_barrier_init.html new file mode 100644 index 0000000..d12434d --- /dev/null +++ b/manual/pthread_barrier_init.html @@ -0,0 +1,187 @@ + + + + + "PTHREAD_BARRIER_DESTROY"(P) manual page + + + + + + + +

POSIX Threads for Windows – REFERENCE - Pthreads-w32

Reference Index

Table of Contents

Name

pthread_barrier_destroy, pthread_barrier_init - destroy and +initialize a barrier object (ADVANCED REALTIME THREADS) +

Synopsis

#include <pthread.h> +

int pthread_barrier_destroy(pthread_barrier_t *barrier); +
int pthread_barrier_init(pthread_barrier_t *restrict barrier, +const pthread_barrierattr_t *restrict attr, unsigned +count); +

Description

The pthread_barrier_destroy function shall destroy the +barrier referenced by barrier and release any resources used +by the barrier. The effect of subsequent use of the barrier is +undefined until the barrier is reinitialized by another call to +pthread_barrier_init . An implementation may use this function +to set barrier to an invalid value. The results are undefined +if pthread_barrier_destroy is called when any thread is +blocked on the barrier, or if this function is called with an +uninitialized barrier. +

The pthread_barrier_init function shall allocate any +resources required to use the barrier referenced by barrier +and shall initialize the barrier with attributes referenced by attr. +If attr is NULL, the default barrier attributes shall be used; +the effect is the same as passing the address of a default barrier +attributes object. The results are undefined if pthread_barrier_init +is called when any thread is blocked on the barrier (that is, has not +returned from the pthread_barrier_wait(3) +call). The results are undefined if a barrier is used without first +being initialized. The results are undefined if pthread_barrier_init +is called specifying an already initialized barrier. +

The count argument specifies the number of threads that +must call pthread_barrier_wait(3) +before any of them successfully return from the call. The value +specified by count must be greater than zero. +

If the pthread_barrier_init function fails, the barrier +shall not be initialized and the contents of barrier are +undefined. +

Only the object referenced by barrier may be used for +performing synchronization. The result of referring to copies of that +object in calls to pthread_barrier_destroy or +pthread_barrier_wait(3) +is undefined.

Return Value

Upon successful completion, these functions shall return zero; +otherwise, an error number shall be returned to indicate the error. +

Errors

The pthread_barrier_destroy +function may fail if: +

EBUSY +: + The implementation has detected an attempt to destroy a barrier + while it is in use (for example, while being used in a + pthread_barrier_wait(3) + call) by another thread. +
+ EINVAL +: + The value specified by barrier is invalid. +

+The pthread_barrier_init function shall fail if: +

EAGAIN +: + The system lacks the necessary resources to initialize another + barrier. +
+ EINVAL +: + The value specified by count is equal to zero. +
+ ENOMEM +: + Insufficient memory exists to initialize the barrier. +

+The pthread_barrier_init function may fail if: +

EBUSY +: + The implementation has detected an attempt to reinitialize a barrier + while it is in use (for example, while being used in a + pthread_barrier_wait(3) + call) by another thread. +
+ EINVAL +: + The value specified by attr is invalid. +

+These functions shall not return an error code of [EINTR]. +

The following sections are informative. +

Examples

None. +

Application Usage

The pthread_barrier_destroy and pthread_barrier_init +functions are part of the Barriers option and need not be provided on +all implementations. +

Pthreads-w32 defines _POSIX_BARRIERS to indicate +that these routines are implemented and may be used.

Rationale

None. +

Future Directions

None. +

Copyright

Modified by Ross Johnson for use with Pthreads-w32.

Table of Contents

Name +
+
Synopsis +
+
Description +
+
Return + Value +
+
Errors +
+
Examples +
+
Application + Usage +
+
Rationale +
+
Future + Directions +
+
See + Also +
+
Copyright +
+

+ + diff --git a/manual/pthread_barrier_wait.html b/manual/pthread_barrier_wait.html new file mode 100644 index 0000000..b44035b --- /dev/null +++ b/manual/pthread_barrier_wait.html @@ -0,0 +1,152 @@ + + + + + "PTHREAD_BARRIER_WAIT"(P) manual page + + + + + + + +

POSIX Threads for Windows – REFERENCE - Pthreads-w32

Reference Index

Table of Contents

Name

pthread_barrier_wait - synchronize at a barrier (ADVANCED +REALTIME THREADS) +

Synopsis

#include <pthread.h> +

int pthread_barrier_wait(pthread_barrier_t *barrier); + +

Description

The pthread_barrier_wait function shall synchronize +participating threads at the barrier referenced by barrier. +The calling thread shall block until the required number of threads +have called pthread_barrier_wait specifying the barrier. +

When the required number of threads have called +pthread_barrier_wait specifying the barrier, the constant +PTHREAD_BARRIER_SERIAL_THREAD shall be returned to one +unspecified thread and zero shall be returned to each of the +remaining threads. At this point, the barrier shall be reset to the +state it had as a result of the most recent pthread_barrier_init(3) +function that referenced it. +

The constant PTHREAD_BARRIER_SERIAL_THREAD is defined in +<pthread.h> and its value shall be distinct from any +other value returned by pthread_barrier_wait . +

The results are undefined if this function is called with an +uninitialized barrier. +

If a signal is delivered to a thread blocked on a barrier, upon +return from the signal handler the thread shall resume waiting at the +barrier if the barrier wait has not completed (that is, if the +required number of threads have not arrived at the barrier during the +execution of the signal handler); otherwise, the thread shall +continue as normal from the completed barrier wait. Until the thread +in the signal handler returns from it, it is unspecified whether +other threads may proceed past the barrier once they have all reached +it. +

A thread that has blocked on a barrier shall not prevent any +unblocked thread that is eligible to use the same processing +resources from eventually making forward progress in its execution. +Eligibility for processing resources shall be determined by the +scheduling policy. +

Return Value

Upon successful completion, the pthread_barrier_wait +function shall return PTHREAD_BARRIER_SERIAL_THREAD for a +single (arbitrary) thread synchronized at the barrier and zero for +each of the other threads. Otherwise, an error number shall be +returned to indicate the error. +

Errors

The pthread_barrier_wait function may fail if: +

EINVAL +: + The value specified by barrier does not refer to an + initialized barrier object. +

+This function shall not return an error code of [EINTR]. +

The following sections are informative. +

Examples

None. +

Application Usage

Applications using this function may be subject to priority +inversion, as discussed in the Base Definitions volume of +IEEE Std 1003.1-2001, Section 3.285, Priority Inversion. +

The pthread_barrier_wait function is part of the Barriers +option and need not be provided on all implementations. +

Pthreads-w32 defines _POSIX_BARRIERS to indicate +that this routine is implemented and may be used.

Rationale

None. +

Future Directions

None. +

Copyright

Modified by Ross Johnson for use with Pthreads-w32.

Table of Contents

Name +
+
Synopsis +
+
Description +
+
Return + Value +
+
Errors +
+
Examples +
+
Application + Usage +
+
Rationale +
+
Future + Directions +
+
See + Also +
+
Copyright +
+

+ + diff --git a/manual/pthread_barrierattr_init.html b/manual/pthread_barrierattr_init.html new file mode 100644 index 0000000..a7c8027 --- /dev/null +++ b/manual/pthread_barrierattr_init.html @@ -0,0 +1,142 @@ + + + + + "PTHREAD_BARRIERATTR_DESTROY"(P) manual page + + + + + + + +

POSIX Threads for Windows – REFERENCE - Pthreads-w32

Reference Index

Table of Contents

Name

pthread_barrierattr_destroy, pthread_barrierattr_init - destroy +and initialize the barrier attributes object (ADVANCED REALTIME +THREADS) +

Synopsis

#include <pthread.h> +

int pthread_barrierattr_destroy(pthread_barrierattr_t *attr); +
int pthread_barrierattr_init(pthread_barrierattr_t *attr); + +

Description

The pthread_barrierattr_destroy function shall destroy a +barrier attributes object. A destroyed attr attributes object +can be reinitialized using pthread_barrierattr_init ; the +results of otherwise referencing the object after it has been +destroyed are undefined. An implementation may cause +pthread_barrierattr_destroy to set the object referenced by +attr to an invalid value. +

The pthread_barrierattr_init function shall initialize a +barrier attributes object attr with the default value for all +of the attributes defined by the implementation. +

Results are undefined if pthread_barrierattr_init is called +specifying an already initialized attr attributes object. +

After a barrier attributes object has been used to initialize one +or more barriers, any function affecting the attributes object +(including destruction) shall not affect any previously initialized +barrier. +

Return Value

If successful, the pthread_barrierattr_destroy and +pthread_barrierattr_init functions shall return zero; +otherwise, an error number shall be returned to indicate the error. +

Errors

The pthread_barrierattr_destroy function may fail if: +

EINVAL +: + The value specified by attr is invalid. +

+The pthread_barrierattr_init function shall fail if: +

ENOMEM +: + Insufficient memory exists to initialize the barrier attributes + object. +

+These functions shall not return an error code of [EINTR]. +

The following sections are informative. +

Examples

None. +

Application Usage

The pthread_barrierattr_destroy and +pthread_barrierattr_init functions are part of the Barriers +option and need not be provided on all implementations. +

Pthreads-w32 defines _POSIX_BARRIERS to indicate +that these routines are implemented and may be used.

Rationale

None. +

Future Directions

None. +

Copyright

Modified by Ross Johnson for use with Pthreads-w32.

Table of Contents

Name +
+
Synopsis +
+
Description +
+
Return + Value +
+
Errors +
+
Examples +
+
Application + Usage +
+
Rationale +
+
Future + Directions +
+
See + Also +
+
Copyright +
+

+ + diff --git a/manual/pthread_barrierattr_setpshared.html b/manual/pthread_barrierattr_setpshared.html new file mode 100644 index 0000000..2c62d3d --- /dev/null +++ b/manual/pthread_barrierattr_setpshared.html @@ -0,0 +1,159 @@ + + + + + "PTHREAD_BARRIERATTR_GETPSHARED"(P) manual page + + + + + + + +

POSIX Threads for Windows – REFERENCE - Pthreads-w32

Reference Index

Table of Contents

Name

pthread_barrierattr_getpshared, pthread_barrierattr_setpshared - +get and set the process-shared attribute of the barrier attributes +object (ADVANCED REALTIME THREADS) +

Synopsis

#include <pthread.h> +

int pthread_barrierattr_getpshared(const pthread_barrierattr_t +* restrict attr, int *restrict pshared); +
int pthread_barrierattr_setpshared(pthread_barrierattr_t *attr, +int pshared); +

Description

The pthread_barrierattr_getpshared function shall obtain +the value of the process-shared attribute from the attributes +object referenced by attr. The pthread_barrierattr_setpshared +function shall set the process-shared attribute in an +initialized attributes object referenced by attr. +

The process-shared attribute is set to +PTHREAD_PROCESS_SHARED to permit a barrier to be operated upon by any +thread that has access to the memory where the barrier is allocated. +If the process-shared attribute is PTHREAD_PROCESS_PRIVATE, +the barrier shall only be operated upon by threads created within the +same process as the thread that initialized the barrier; if threads +of different processes attempt to operate on such a barrier, the +behavior is undefined. The default value of the attribute shall be +PTHREAD_PROCESS_PRIVATE. Both constants PTHREAD_PROCESS_SHARED and +PTHREAD_PROCESS_PRIVATE are defined in <pthread.h>. +

Pthreads-w32 defines _POSIX_THREAD_PROCESS_SHARED in +pthread.h as -1 to indicate that these routines are implemented but +that the process shared attribute is not supported.

Additional attributes, their default values, and the names of the +associated functions to get and set those attribute values are +implementation-defined. +

Return Value

If successful, the pthread_barrierattr_getpshared function +shall return zero and store the value of the process-shared +attribute of attr into the object referenced by the pshared +parameter. Otherwise, an error number shall be returned to indicate +the error. +

If successful, the pthread_barrierattr_setpshared function +shall return zero; otherwise, an error number shall be returned to +indicate the error. +

Errors

These functions may fail if: +

EINVAL +: + The value specified by attr is invalid. +
+ The pthread_barrierattr_setpshared function may fail if: +
+ EINVAL +: + The new value specified for the process-shared attribute is + not one of the legal values PTHREAD_PROCESS_SHARED or + PTHREAD_PROCESS_PRIVATE. +
+ ENOSYS +: + The value specified by attr was PTHREAD_PROCESS_SHARED + (Pthreads-w32).

+These functions shall not return an error code of [EINTR]. +

The following sections are informative. +

Examples

None. +

Application Usage

The pthread_barrierattr_getpshared and +pthread_barrierattr_setpshared functions are part of the +Barriers option and need not be provided on all implementations. +

Pthreads-w32 defines _POSIX_BARRIERS and +_POSIX_THREAD_PROCESS_SHARED in pthread.h as -1 to indicate +that these routines are implemented and may be used, but do not +support the process shared option.

Rationale

None. +

Future Directions

None. +

Copyright

Modified by Ross Johnson for use with Pthreads-w32.

Table of Contents

Name +
+
Synopsis +
+
Description +
+
Return + Value +
+
Errors +
+
Examples +
+
Application + Usage +
+
Rationale +
+
Future + Directions +
+
See + Also +
+
Copyright +
+

+ + diff --git a/manual/pthread_cancel.html b/manual/pthread_cancel.html new file mode 100644 index 0000000..d9acd77 --- /dev/null +++ b/manual/pthread_cancel.html @@ -0,0 +1,205 @@ + + + + + PTHREAD_CANCEL(3) manual page + + + + + + + +

POSIX Threads for Windows – REFERENCE - Pthreads-w32

Reference Index

Table of Contents

Name

pthread_cancel, pthread_setcancelstate, pthread_setcanceltype, +pthread_testcancel - thread cancellation +

Synopsis

#include <pthread.h> +

int pthread_cancel(pthread_t thread); +

int pthread_setcancelstate(int state, int +*oldstate); +

int pthread_setcanceltype(int type, int +*oldtype); +

void pthread_testcancel(void); +

Description

Cancellation is the mechanism by which a thread can terminate the +execution of another thread. More precisely, a thread can send a +cancellation request to another thread. Depending on its settings, +the target thread can then either ignore the request, honor it +immediately, or defer it until it reaches a cancellation point. +

When a thread eventually honors a cancellation request, it +performs as if pthread_exit(PTHREAD_CANCELED) has been called +at that point: all cleanup handlers are executed in reverse order, +destructor functions for thread-specific data are called, and finally +the thread stops executing with the return value PTHREAD_CANCELED. +See pthread_exit(3) for more +information. +

pthread_cancel sends a cancellation request to the thread +denoted by the thread argument. +

pthread_setcancelstate changes the cancellation state for +the calling thread -- that is, whether cancellation requests are +ignored or not. The state argument is the new cancellation +state: either PTHREAD_CANCEL_ENABLE to enable cancellation, or +PTHREAD_CANCEL_DISABLE to disable cancellation (cancellation +requests are ignored). If oldstate is not NULL, the +previous cancellation state is stored in the location pointed to by +oldstate, and can thus be restored later by another call to +pthread_setcancelstate. +

pthread_setcanceltype changes the type of responses to +cancellation requests for the calling thread: asynchronous +(immediate) or deferred. The type argument is the new +cancellation type: either PTHREAD_CANCEL_ASYNCHRONOUS to +cancel the calling thread as soon as the cancellation request is +received, or PTHREAD_CANCEL_DEFERRED to keep the cancellation +request pending until the next cancellation point. If oldtype +is not NULL, the previous cancellation state is stored in the +location pointed to by oldtype, and can thus be restored later +by another call to pthread_setcanceltype. +

Pthreads-w32 provides two levels of support for +PTHREAD_CANCEL_ASYNCHRONOUS: full and partial. Full support +requires an additional DLL and driver be installed on the Windows +system (see the See Also section below) that allows blocked threads +to be cancelled immediately. Partial support means that the target +thread will not cancel until it resumes execution naturally. Partial +support is provided if either the DLL or the driver are not +automatically detected by the pthreads-w32 library at run-time.

Threads are always created by pthread_create(3) +with cancellation enabled and deferred. That is, the initial +cancellation state is PTHREAD_CANCEL_ENABLE and the initial +type is PTHREAD_CANCEL_DEFERRED. +

Cancellation points are those points in the program execution +where a test for pending cancellation requests is performed and +cancellation is executed if positive. The following POSIX threads +functions are cancellation points: +

pthread_join(3) +
pthread_cond_wait(3) +
pthread_cond_timedwait(3) +
pthread_testcancel(3)
sem_wait(3) +
sem_timedwait(3)
sigwait(3)

Pthreads-w32 provides two functions to enable additional +cancellation points to be created in user functions that block on +Win32 HANDLEs:

pthreadCancelableWait() +
pthreadCancelableTimedWait()

All other POSIX threads functions are guaranteed not to be +cancellation points. That is, they never perform cancellation in +deferred cancellation mode. +

pthread_testcancel does nothing except testing for pending +cancellation and executing it. Its purpose is to introduce explicit +checks for cancellation in long sequences of code that do not call +cancellation point functions otherwise. +

Return Value

pthread_cancel, pthread_setcancelstate and +pthread_setcanceltype return 0 on success and a non-zero error +code on error. +

Errors

pthread_cancel returns the following error code on error: +

ESRCH +: + no thread could be found corresponding to that specified by the + thread ID. +

+ +

+pthread_setcancelstate returns the following error code on +error: +

EINVAL +: + the state argument is not +

+ +

+PTHREAD_CANCEL_ENABLE nor PTHREAD_CANCEL_DISABLE +

pthread_setcanceltype returns the following error code on +error: +

EINVAL +: + the type argument is not +

+ +

+PTHREAD_CANCEL_DEFERRED nor PTHREAD_CANCEL_ASYNCHRONOUS +

Author

Xavier Leroy <Xavier.Leroy@inria.fr> +

Modified by Ross Johnson for use with Pthreads-w32.

Bugs

POSIX specifies that a number of system calls (basically, all +system calls that may block, such as read(2) +, write(2) , wait(2) +, etc.) and library functions that may call these system calls (e.g. +fprintf(3) ) are cancellation +points. Pthreads-win32 is not integrated enough with the C +library to implement this, and thus none of the C library functions +is a cancellation point. +

A workaround for these calls is to temporarily switch to +asynchronous cancellation (assuming full asynchronous cancellation +support is installed). So, checking for cancellation during a read +system call, for instance, can be achieved as follows: +

+

pthread_setcanceltype(PTHREAD_CANCEL_ASYNCHRONOUS, &oldCancelType);
+read(fd, buffer, length);
+pthread_setcanceltype(oldCancelType, NULL);

Table of Contents

Name +
+
Synopsis +
+
Description +
+
Return + Value +
+
Errors +
+
Author +
+
See + Also +
+
Bugs +
+

+ + diff --git a/manual/pthread_cleanup_push.html b/manual/pthread_cleanup_push.html new file mode 100644 index 0000000..0fc071e --- /dev/null +++ b/manual/pthread_cleanup_push.html @@ -0,0 +1,140 @@ + + + + + PTHREAD_CLEANUP(3) manual page + + + + + + + +

POSIX Threads for Windows – REFERENCE - Pthreads-w32

Reference Index

Table of Contents

Name

pthread_cleanup_push, pthread_cleanup_pop - install and remove +cleanup handlers +

Synopsis

#include <pthread.h> +

void pthread_cleanup_push(void (*routine) (void +*), void *arg); +

void pthread_cleanup_pop(int execute); +

Description

Cleanup handlers are functions that get called when a thread +terminates, either by calling pthread_exit(3) +or because of cancellation. Cleanup handlers are installed and +removed following a stack-like discipline. +

The purpose of cleanup handlers is to free the resources that a +thread may hold at the time it terminates. In particular, if a thread +exits or is cancelled while it owns a locked mutex, the mutex will +remain locked forever and prevent other threads from executing +normally. The best way to avoid this is, just before locking the +mutex, to install a cleanup handler whose effect is to unlock the +mutex. Cleanup handlers can be used similarly to free blocks +allocated with malloc(3) or close +file descriptors on thread termination. +

pthread_cleanup_push installs the routine function +with argument arg as a cleanup handler. From this point on to +the matching pthread_cleanup_pop, the function routine +will be called with arguments arg when the thread terminates, +either through pthread_exit(3) +or by cancellation. If several cleanup handlers are active at that +point, they are called in LIFO order: the most recently installed +handler is called first. +

pthread_cleanup_pop removes the most recently installed +cleanup handler. If the execute argument is not 0, it also +executes the handler, by calling the routine function with +arguments arg. If the execute argument is 0, the +handler is only removed but not executed. +

Matching pairs of pthread_cleanup_push and +pthread_cleanup_pop must occur in the same function, at the +same level of block nesting. Actually, pthread_cleanup_push +and pthread_cleanup_pop are macros, and the expansion of +pthread_cleanup_push introduces an open brace { with +the matching closing brace } being introduced by the expansion +of the matching pthread_cleanup_pop. +

Return Value

None. +

Errors

None. +

Author

Xavier Leroy +<Xavier.Leroy@inria.fr> +

Modified by +Ross Johnson for use with Pthreads-w32.

Example

Here is how +to lock a mutex mut in such a way that it will be unlocked if +the thread is canceled while mut is locked: +

pthread_cleanup_push(pthread_mutex_unlock, (void *) &mut);
+pthread_mutex_lock(&mut);
+/* do some work */
+pthread_mutex_unlock(&mut);
+pthread_cleanup_pop(0);

+Equivalently, the last two lines can be replaced by +

pthread_cleanup_pop(1);

+Notice that the code above is safe only in deferred cancellation mode +(see pthread_setcanceltype(3) +). In asynchronous cancellation mode, a cancellation can occur +between pthread_cleanup_push and pthread_mutex_lock, or +between pthread_mutex_unlock and pthread_cleanup_pop, +resulting in both cases in the thread trying to unlock a mutex not +locked by the current thread. This is the main reason why +asynchronous cancellation is difficult to use. +

If the code +above must also work in asynchronous cancellation mode, then it must +switch to deferred mode for locking and unlocking the mutex: +

pthread_setcanceltype(PTHREAD_CANCEL_DEFERRED, &oldtype);
+pthread_cleanup_push(pthread_mutex_unlock, (void *) &mut);
+pthread_mutex_lock(&mut);
+/* do some work */
+pthread_cleanup_pop(1);
+pthread_setcanceltype(oldtype, NULL);

+Table of Contents

Name +
+
Synopsis +
+
Description +
+
Return + Value +
+
Errors +
+
Author +
+
See + Also +
+
Example +
+

+ + diff --git a/manual/pthread_cond_init.html b/manual/pthread_cond_init.html new file mode 100644 index 0000000..937e490 --- /dev/null +++ b/manual/pthread_cond_init.html @@ -0,0 +1,313 @@ + + + + + PTHREAD_COND(3) manual page + + + + + + + +

POSIX Threads for Windows – REFERENCE - Pthreads-w32

Reference Index

Table of Contents

Name

pthread_cond_init, pthread_cond_destroy, pthread_cond_signal, +pthread_cond_broadcast, pthread_cond_wait, pthread_cond_timedwait - +operations on conditions +

Synopsis

#include <pthread.h> +

pthread_cond_t cond = PTHREAD_COND_INITIALIZER; +

int pthread_cond_init(pthread_cond_t *cond, +pthread_condattr_t *cond_attr); +

int pthread_cond_signal(pthread_cond_t *cond); +

int pthread_cond_broadcast(pthread_cond_t *cond); +

int pthread_cond_wait(pthread_cond_t *cond, +pthread_mutex_t *mutex); +

int pthread_cond_timedwait(pthread_cond_t *cond, +pthread_mutex_t *mutex, const struct timespec +*abstime); +

int pthread_cond_destroy(pthread_cond_t *cond); +

Description

A condition (short for ‘‘condition variable’’) is a +synchronization device that allows threads to suspend execution and +relinquish the processors until some predicate on shared data is +satisfied. The basic operations on conditions are: signal the +condition (when the predicate becomes true), and wait for the +condition, suspending the thread execution until another thread +signals the condition. +

A condition variable must always be associated with a mutex, to +avoid the race condition where a thread prepares to wait on a +condition variable and another thread signals the condition just +before the first thread actually waits on it. +

pthread_cond_init initializes the condition variable cond, +using the condition attributes specified in cond_attr, or +default attributes if cond_attr is NULL. +

Variables of type pthread_cond_t can also be initialized +statically, using the constant PTHREAD_COND_INITIALIZER. In +the Pthreads-w32 implementation, an application should still +call pthread_cond_destroy at some point to ensure that any +resources consumed by the condition variable are released.

pthread_cond_signal restarts one of the threads that are +waiting on the condition variable cond. If no threads are +waiting on cond, nothing happens. If several threads are +waiting on cond, exactly one is restarted, but it is not +specified which. +

pthread_cond_broadcast restarts all the threads that are +waiting on the condition variable cond. Nothing happens if no +threads are waiting on cond. +

pthread_cond_wait atomically unlocks the mutex (as +per pthread_unlock_mutex) and waits for the condition variable +cond to be signalled. The thread execution is suspended and +does not consume any CPU time until the condition variable is +signalled. The mutex must be locked by the calling thread on +entrance to pthread_cond_wait. Before returning to the calling +thread, pthread_cond_wait re-acquires mutex (as per +pthread_lock_mutex). +

Unlocking the mutex and suspending on the condition variable is +done atomically. Thus, if all threads always acquire the mutex before +signalling the condition, this guarantees that the condition cannot +be signalled (and thus ignored) between the time a thread locks the +mutex and the time it waits on the condition variable. +

pthread_cond_timedwait atomically unlocks mutex and +waits on cond, as pthread_cond_wait does, but it also +bounds the duration of the wait. If cond has not been +signalled within the amount of time specified by abstime, the +mutex mutex is re-acquired and pthread_cond_timedwait +returns the error ETIMEDOUT. The abstime parameter +specifies an absolute time, with the same origin as time(2) +and gettimeofday(2). +

pthread_cond_destroy destroys a condition variable, freeing +the resources it might hold. No threads must be waiting on the +condition variable on entrance to pthread_cond_destroy.

Cancellation

pthread_cond_wait and pthread_cond_timedwait are +cancellation points. If a thread is cancelled while suspended in one +of these functions, the thread immediately resumes execution, then +locks again the mutex argument to pthread_cond_wait and +pthread_cond_timedwait, and finally executes the cancellation. +Consequently, cleanup handlers are assured that mutex is +locked when they are called. +

Async-signal Safety

The condition functions are not async-signal safe, and should not +be called from a signal handler. In particular, calling +pthread_cond_signal or pthread_cond_broadcast from a +signal handler may deadlock the calling thread. +

Return Value

All condition variable functions return 0 on success and a +non-zero error code on error. +

Errors

pthread_cond_init, pthread_cond_signal, +pthread_cond_broadcast, and pthread_cond_wait never +return an error code. +

The pthread_cond_init function returns the following error +codes on error: +

EINVAL +: + The cond argument is invalid. +
+ ENOMEM +

+ +

+There was not enough memory to allocate the condition variable. +

The pthread_cond_signal function returns the following +error codes on error: +

EINVAL +: + The cond argument is invalid. +

+ +

+The pthread_cond_broadcast function returns the following +error codes on error: +

EINVAL +: + The cond argument is invalid. +

+ +

+The pthread_cond_wait function returns the following error +codes on error: +

EINVAL +: + The cond argument is invalid. +
+ ENOMEM +

+ +

+There was not enough memory to allocate the statically initialised +condition variable. Statically initialised condition variables are +dynamically allocated by the first thread to wait on them.

The pthread_cond_timedwait function returns the following +error codes on error: +

EINVAL +

+ +

+The cond argument is invalid. +

ETIMEDOUT +: + The condition variable was not signalled before the timeout + specified by abstime +
+ ENOMEM +

+ +

+There was not enough memory to allocate the statically initialised +condition variable. Statically initialised condition variables are +dynamically allocated by the first thread to wait on them. +

The pthread_cond_destroy function returns the following +error code on error: +

EINVAL +

+ +

+The cond argument is invalid. +

EBUSY +: + Some threads are currently waiting on cond. +

+ +

+Author

Xavier Leroy <Xavier.Leroy@inria.fr> +

Modified by Ross Johnson for use with Pthreads-w32.

Example

Consider two shared variables x and y, protected by +the mutex mut, and a condition variable cond that is to +be signaled whenever x becomes greater than y. +

int x,y;
+pthread_mutex_t mut = PTHREAD_MUTEX_INITIALIZER;
+pthread_cond_t cond = PTHREAD_COND_INITIALIZER;

+Waiting until x is greater than y is performed as +follows: +

pthread_mutex_lock(&mut);
+while (x <= y) {
+        pthread_cond_wait(&cond, &mut);
+}
+/* operate on x and y */
+pthread_mutex_unlock(&mut);

+Modifications on x and y that may cause x to +become greater than y should signal the condition if needed: +

pthread_mutex_lock(&mut);
+/* modify x and y */
+if (x > y) pthread_cond_broadcast(&cond);
+pthread_mutex_unlock(&mut);

+If it can be proved that at most one waiting thread needs to be waken +up (for instance, if there are only two threads communicating through +x and y), pthread_cond_signal can be used as a +slightly more efficient alternative to pthread_cond_broadcast. +If in doubt, use pthread_cond_broadcast. +

To wait for x to +become greater than y with a timeout of 5 seconds, do: +

struct timeval now;
+struct timespec timeout;
+int retcode;
+pthread_mutex_lock(&mut);
+gettimeofday(&now);
+timeout.tv_sec = now.tv_sec + 5;
+timeout.tv_nsec = now.tv_usec * 1000;
+retcode = 0;
+while (x <= y && retcode != ETIMEDOUT) {
+        retcode = pthread_cond_timedwait(&cond, &mut, &timeout);
+}
+if (retcode == ETIMEDOUT) {
+        /* timeout occurred */
+} else {
+        /* operate on x and y */
+}
+pthread_mutex_unlock(&mut);

+Table of Contents

Name +
+
Synopsis +
+
Description +
+
Cancellation +
+
Async-signal + Safety +
+
Return + Value +
+
Errors +
+
Author +
+
See + Also +
+
Example +
+

+ + diff --git a/manual/pthread_condattr_init.html b/manual/pthread_condattr_init.html new file mode 100644 index 0000000..8b8b2f2 --- /dev/null +++ b/manual/pthread_condattr_init.html @@ -0,0 +1,98 @@ + + + + + PTHREAD_CONDATTR(3) manual page + + + + + + + +

POSIX Threads for Windows – REFERENCE - Pthreads-w32

Reference Index

Table of Contents

Name

pthread_condattr_init, pthread_condattr_destroy - condition +creation +

attributes +

Synopsis

#include <pthread.h> +

int pthread_condattr_init(pthread_condattr_t *attr); +

int pthread_condattr_destroy(pthread_condattr_t *attr); +

Description

Condition attributes can be specified at condition creation time, +by passing a condition attribute object as second argument to +pthread_cond_init(3) . +Passing NULL is equivalent to passing a condition attribute +object with all attributes set to their default values. +

pthread_condattr_init initializes the condition attribute +object attr and fills it with default values for the +attributes. pthread_condattr_destroy destroys a condition +attribute object, which must not be reused until it is reinitialized.

Pthreads-w32 defines _POSIX_THREAD_PROCESS_SHARED in +pthread.h as -1 to indicate that the attribute routines are +implemented but that the process shared attribute is not supported.

Return Value

All condition variable functions return 0 on success and a +non-zero error code on error.

Errors

The pthread_condattr_init function returns the following +error code on error: +

ENOMEM +: + The was insufficient memory to create the attribute. + +

+ +

+The pthread_condattr_destroy function returns the following +error code on error: +

EINVAL +: + The attr argument is not valid. + +

+ +

+Author

Xavier Leroy <Xavier.Leroy@inria.fr> +

Modified by Ross Johnson for use with Pthreads-w32.

Name

pthread_condattr_getpshared, pthread_condattr_setpshared - get and +set the process-shared condition variable attributes +

Synopsis

#include <pthread.h> +

int pthread_condattr_getpshared(const pthread_condattr_t +*restrict attr, int *restrict pshared); +
int pthread_condattr_setpshared(pthread_condattr_t *attr, +int pshared); +

Description

The pthread_condattr_getpshared function shall obtain the +value of the process-shared attribute from the attributes +object referenced by attr. The pthread_condattr_setpshared +function shall set the process-shared attribute in an +initialized attributes object referenced by attr. +

The process-shared attribute is set to +PTHREAD_PROCESS_SHARED to permit a condition variable to be +operated upon by any thread that has access to the memory where the +condition variable is allocated, even if the condition variable is +allocated in memory that is shared by multiple processes. If the +process-shared attribute is PTHREAD_PROCESS_PRIVATE, +the condition variable shall only be operated upon by threads created +within the same process as the thread that initialized the condition +variable; if threads of differing processes attempt to operate on +such a condition variable, the behavior is undefined. The default +value of the attribute is PTHREAD_PROCESS_PRIVATE. +

Pthreads-w32 defines _POSIX_THREAD_PROCESS_SHARED in +pthread.h as -1 to indicate that these routines are implemented but +that the process shared attribute is not supported.

Return Value

If successful, the pthread_condattr_setpshared function +shall return zero; otherwise, an error number shall be returned to +indicate the error. +

If successful, the pthread_condattr_getpshared function +shall return zero and store the value of the process-shared +attribute of attr into the object referenced by the pshared +parameter. Otherwise, an error number shall be returned to indicate +the error. +

Errors

The pthread_condattr_getpshared and +pthread_condattr_setpshared functions may fail if: +

EINVAL +: + The value specified by attr is invalid. +

+The pthread_condattr_setpshared function may fail if: +

EINVAL +: + The new value specified for the attribute is outside the range of + legal values for that attribute. +
+ ENOSYS +: + The value specified by attr was PTHREAD_PROCESS_SHARED + (Pthreads-w32).

+These functions shall not return an error code of [EINTR]. +

The following sections are informative. +

Examples

None. +

Application Usage

Pthreads-w32 defines _POSIX_THREAD_PROCESS_SHARED in +pthread.h as -1 to indicate that these routines are implemented and +may be used, but do not support the process shared option.

Rationale

None. +

Future Directions

None. +

Copyright

Modified by Ross Johnson for use with Pthreads-w32.

Table of Contents

Name +
+
Synopsis +
+
Description +
+
Return + Value +
+
Errors +
+
Examples +
+
Application + Usage +
+
Rationale +
+
Future + Directions +
+
See + Also +
+
Copyright +
+

+ + diff --git a/manual/pthread_create.html b/manual/pthread_create.html new file mode 100644 index 0000000..d1ebbc3 --- /dev/null +++ b/manual/pthread_create.html @@ -0,0 +1,94 @@ + + + + + PTHREAD_CREATE(3) manual page + + + + + + + +

POSIX Threads for Windows – REFERENCE - Pthreads-w32

Reference Index

Table of Contents

Name

pthread_create - create a new thread +

Synopsis

#include <pthread.h> +

int pthread_create(pthread_t * thread, +pthread_attr_t * attr, void * (*start_routine)(void +*), void * arg); +

Description

pthread_create creates a new thread of control that +executes concurrently with the calling thread. The new thread applies +the function start_routine passing it arg as first +argument. The new thread terminates either explicitly, by calling +pthread_exit(3) , or +implicitly, by returning from the start_routine function. The +latter case is equivalent to calling pthread_exit(3) +with the result returned by start_routine as exit code. +

The initial signal state of the new thread is inherited from it's +creating thread and there are no pending signals. Pthreads-w32 +does not yet implement signals.

The attr argument specifies thread attributes to be applied +to the new thread. See pthread_attr_init(3) +for a complete list of thread attributes. The attr argument +can also be NULL, in which case default attributes are used: +the created thread is joinable (not detached) and has default (non +real-time) scheduling policy. +

Return Value

On success, the identifier of the newly created thread is stored +in the location pointed by the thread argument, and a 0 is +returned. On error, a non-zero error code is returned. +

Errors

EAGAIN +

+Author

Xavier Leroy <Xavier.Leroy@inria.fr> +

Modified by Ross Johnson for use with Pthreads-w32.

Name

pthread_delay_np – suspend the +thread for a specified period

Synopsis

#include <pthread.h> +

int pthread_delay_np (const struct timespec *interval);

Description

pthread_delay_np causes a thread to delay execution for a +specific period of time. This period ends at the current time plus +the specified interval. The routine will not return before the end of +the period is reached, but may return an arbitrary amount of time +after the period has gone by. This can be due to system load, thread +priorities, and system timer granularity.

Specifying an interval of zero (0) seconds and zero (0) +nanoseconds is allowed and can be used to force the thread to give up +the processor or to deliver a pending cancellation request.

Cancellation

pthread_delay_np is a cancellation point.

Return Value

If an error condition occurs, pthread_delay_np returns an +integer value indicating the type of error.

Errors

The pthread_delay_np function returns the following error +code on error: +

EINVAL +

+ +

+The value specified by interval is invalid.

Author

Ross Johnson for use with Pthreads-w32.

Table of Contents

Name +
+
Synopsis +
+
Description +
+
Cancellation +
+
Return + Value +
+
Errors +
+
Author +
+

+ + diff --git a/manual/pthread_detach.html b/manual/pthread_detach.html new file mode 100644 index 0000000..265a467 --- /dev/null +++ b/manual/pthread_detach.html @@ -0,0 +1,86 @@ + + + + + PTHREAD_DETACH(3) manual page + + + + + + + +

POSIX Threads for Windows – REFERENCE - Pthreads-w32

Reference Index

Table of Contents

Name

pthread_detach - put a running thread in the detached state +

Synopsis

#include <pthread.h> +

int pthread_detach(pthread_t th); +

Description

pthread_detach puts the thread th in the detached +state. This guarantees that the memory resources consumed by th +will be freed immediately when th terminates. However, this +prevents other threads from synchronizing on the termination of th +using pthread_join. +

A thread can be created initially in the detached state, using the +detachstate attribute to pthread_create(3) +. In contrast, pthread_detach applies to threads created in +the joinable state, and which need to be put in the detached state +later. +

After pthread_detach completes, subsequent attempts to +perform pthread_join on th will fail. If another thread +is already joining the thread th at the time pthread_detach +is called, pthread_detach does nothing and leaves th in +the joinable state. +

Return Value

On success, 0 is returned. On error, a non-zero error code is +returned. +

Errors

ESRCH +: + No thread could be found corresponding to that specified by th +
+ EINVAL +: + the thread th is already in the detached state +

+Author

Xavier Leroy <Xavier.Leroy@inria.fr> +

Name

+pthread_equal - compare two thread identifiers +

Synopsis

+#include <pthread.h> + +

int pthread_equal(pthread_t thread1, pthread_t thread2); +

Description

+pthread_equal +determines if two thread identifiers refer to the same thread. +

Return Value

+A +non-zero value is returned if thread1 and thread2 refer to the same thread. +Otherwise, 0 is returned. +

Author

+Xavier Leroy <Xavier.Leroy@inria.fr> +

Name

+pthread_exit - terminate the calling thread +

Synopsis

+#include <pthread.h> + +

void pthread_exit(void *retval); +

Description

+pthread_exit terminates the +execution of the calling thread. All cleanup handlers that have been set +for the calling thread with pthread_cleanup_push(3) + are executed in reverse +order (the most recently pushed handler is executed first). Finalization +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(3) +). +Finally, execution of the calling thread is stopped. +

The retval argument +is the return value of the thread. It can be consulted from another thread +using pthread_join(3) +. +

Return Value

+The pthread_exit function never returns. + +

Author

+Xavier Leroy <Xavier.Leroy@inria.fr> +

Name

pthread_getw32threadhandle_np – get +the Win32 thread handle associated with a thread

Synopsis

#include <pthread.h> +

HANDLE pthread_getw32threadhandle_np(pthread_t thread);

Description

Returns the Win32 native thread HANDLE that the POSIX +thread thread is running as.

Applications can use the Win32 handle to set Win32 specific +attributes of the thread.

Cancellation

None.

Return Value

pthread_getw32threadhandle_np returns the Win32 native +thread HANDLE for the specified POSIX thread thread.

Errors

None.

Author

Ross Johnson for use with Pthreads-w32.

Table of Contents

Name +
+
Synopsis +
+
Description +
+
Cancellation +
+
Return + Value +
+
Errors +
+
Author +
+

+ + diff --git a/manual/pthread_join.html b/manual/pthread_join.html new file mode 100644 index 0000000..3e3f3b9 --- /dev/null +++ b/manual/pthread_join.html @@ -0,0 +1,118 @@ + + + + + PTHREAD_JOIN(3) manual page + + + + + + + +

POSIX Threads for Windows – REFERENCE - Pthreads-w32

Reference Index

Table of Contents

Name

pthread_join - wait for termination of another thread +

Synopsis

#include <pthread.h> +

int pthread_join(pthread_t th, void +**thread_return); +

Description

pthread_join suspends the execution of the calling thread +until the thread identified by th terminates, either by +calling pthread_exit(3) or by +being cancelled. +

If thread_return is not NULL, the return value of th +is stored in the location pointed to by thread_return. The +return value of th is either the argument it gave to +pthread_exit(3) , or +PTHREAD_CANCELED if th was cancelled. +

The joined thread th must be in the joinable state: it must +not have been detached using pthread_detach(3) +or the PTHREAD_CREATE_DETACHED attribute to pthread_create(3) +. +

When a joinable thread terminates, its memory resources (thread +descriptor and stack) are not deallocated until another thread +performs pthread_join on it. Therefore, pthread_join +must be called once for each joinable thread created to avoid memory +leaks. +

At most one thread can wait for the termination of a given thread. +Calling pthread_join on a thread th on which another +thread is already waiting for termination returns an error. +

Cancellation

pthread_join is a cancellation point. If a thread is +cancelled while suspended in pthread_join, the thread +execution resumes immediately and the cancellation is executed +without waiting for the th thread to terminate. If +cancellation occurs during pthread_join, the th thread +remains not joined. +

Return Value

On success, the return value of th is stored in the +location pointed to by thread_return, and 0 is returned. On +error, a non-zero error code is returned. +

Errors

ESRCH +: + No thread could be found corresponding to that specified by th. +
+ EINVAL +: + The th thread has been detached. +
+ EINVAL +: + Another thread is already waiting on termination of th. +
+ EDEADLK +: + The th argument refers to the calling thread. +

+Author

Xavier Leroy <Xavier.Leroy@inria.fr> +

Name

pthread_key_create, pthread_key_delete, pthread_setspecific, +pthread_getspecific - management of thread-specific data +

Synopsis

#include <pthread.h> +

int pthread_key_create(pthread_key_t *key, void +(*destr_function) (void *)); +

int pthread_key_delete(pthread_key_t key); +

int pthread_setspecific(pthread_key_t key, const +void *pointer); +

void * pthread_getspecific(pthread_key_t key); +

Description

Programs often need global or static variables that have different +values in different threads. Since threads share one memory space, +this cannot be achieved with regular variables. Thread-specific data +is the POSIX threads answer to this need. +

Each thread possesses a private memory block, the thread-specific +data area, or TSD area for short. This area is indexed by TSD keys. +The TSD area associates values of type void * to TSD keys. TSD +keys are common to all threads, but the value associated with a given +TSD key can be different in each thread. +

For concreteness, the TSD areas can be viewed as arrays of void +* pointers, TSD keys as integer indices into these arrays, and +the value of a TSD key as the value of the corresponding array +element in the calling thread. +

When a thread is created, its TSD area initially associates NULL +with all keys. +

pthread_key_create allocates a new TSD key. The key is +stored in the location pointed to by key. There is a limit of +PTHREAD_KEYS_MAX on the number of keys allocated at a given +time. The value initially associated with the returned key is NULL +in all currently executing threads. +

The destr_function argument, if not NULL, specifies +a destructor function associated with the key. When a thread +terminates via pthread_exit or by cancellation, destr_function +is called with arguments the value associated with the key in that +thread. The destr_function is not called if that value is +NULL. The order in which destructor functions are called at +thread termination time is unspecified. +

Before the destructor function is called, the NULL value is +associated with the key in the current thread. A destructor function +might, however, re-associate non- NULL values to that key or +some other key. To deal with this, if after all the destructors have +been called for all non- NULL values, there are still some +non- NULL values with associated destructors, then the process +is repeated. The LinuxThreads implementation stops the process after +PTHREAD_DESTRUCTOR_ITERATIONS iterations, even if some non- +NULL values with associated descriptors remain. Other +implementations may loop indefinitely. +

pthread_key_delete deallocates a TSD key. It does not check +whether non- NULL values are associated with that key in the +currently executing threads, nor call the destructor function +associated with the key. +

pthread_setspecific changes the value associated with key +in the calling thread, storing the given pointer instead. +

pthread_getspecific returns the value currently associated +with key in the calling thread. +

Return Value

pthread_key_create, pthread_key_delete, and +pthread_setspecific return 0 on success and a non-zero error +code on failure. If successful, pthread_key_create stores the +newly allocated key in the location pointed to by its key +argument. +

pthread_getspecific returns the value associated with key +on success, and NULL on error. +

Errors

pthread_key_create returns the following error code on +error: +

EAGAIN +

+ +

+PTHREAD_KEYS_MAX keys are already allocated +

ENOMEM +

+ +

+Insufficient memory to allocate the key. +

pthread_key_delete and pthread_setspecific return +the following error code on error: +

EINVAL +: + key is not a valid, allocated TSD key +

+ +

+pthread_getspecific returns NULL if key is not a +valid, allocated TSD key. +

Author

Xavier Leroy <Xavier.Leroy@inria.fr> +

Modified by Ross Johnson for use with Pthreads-w32.

Example

The following code fragment allocates a thread-specific array of +100 characters, with automatic reclamation at thread exit: +

+

/* Key for the thread-specific buffer */
+static pthread_key_t buffer_key;
+/* Once-only initialisation of the key */
+static pthread_once_t buffer_key_once = PTHREAD_ONCE_INIT;
+/* Allocate the thread-specific buffer */
+void buffer_alloc(void)
+{
+  pthread_once(&buffer_key_once, buffer_key_alloc);
+  pthread_setspecific(buffer_key, malloc(100));
+}
+/* Return the thread-specific buffer */
+char * get_buffer(void)
+{
+  return (char *) pthread_getspecific(buffer_key);
+}
+/* Allocate the key */
+static void buffer_key_alloc()
+{
+  pthread_key_create(&buffer_key, buffer_destroy);
+}
+/* Free the thread-specific buffer */
+static void buffer_destroy(void * buf)
+{
+  free(buf);
+}

Table of +Contents

Name +
+
Synopsis +
+
Description +
+
Return + Value +
+
Errors +
+
Author +
+
See + Also +
+
Example +
+

+ + diff --git a/manual/pthread_kill.html b/manual/pthread_kill.html new file mode 100644 index 0000000..33d61b2 --- /dev/null +++ b/manual/pthread_kill.html @@ -0,0 +1,152 @@ + + + + + PTHREAD_SIGNAL(3) manual page + + + + + + + +

POSIX Threads for Windows – REFERENCE - Pthreads-w32

Reference Index

Table of Contents

Name

pthread_sigmask, pthread_kill, sigwait - handling of signals in +threads +

Synopsis

#include <pthread.h>
#include <signal.h> +

int pthread_sigmask(int how, const sigset_t +*newmask, sigset_t *oldmask); +

int pthread_kill(pthread_t thread, int signo); +

int sigwait(const sigset_t *set, int *sig);

Description

pthread_sigmask changes the signal mask for the calling +thread as described by the how and newmask arguments. +If oldmask is not NULL, the previous signal mask is +stored in the location pointed to by oldmask. Pthreads-w32 +implements this function but no other function uses the signal mask +yet.

The meaning of the how and newmask arguments is the +same as for sigprocmask(2). +If how is SIG_SETMASK, the signal mask is set to +newmask. If how is SIG_BLOCK, the signals +specified to newmask are added to the current signal mask. If +how is SIG_UNBLOCK, the signals specified to newmask +are removed from the current signal mask. +

Recall that signal masks are set on a per-thread basis, but signal +actions and signal handlers, as set with sigaction(2), are +shared between all threads. +

pthread_kill send signal number signo to the thread +thread. Pthreads-w32 only supports signal number 0, +which does not send any signal but causes pthread_kill to +return an error if thread is not valid.

sigwait suspends the calling thread until one of the +signals in set is delivered to the calling thread. It then +stores the number of the signal received in the location pointed to +by sig and returns. The signals in set must be blocked +and not ignored on entrance to sigwait. If the delivered +signal has a signal handler function attached, that function is not +called. Pthreads-w32 implements this function as a +cancellation point only - it does not wait for any signals and does +not change the location pointed to by sig.

Cancellation

sigwait is a cancellation point. +

Return Value

On success, 0 is returned. On failure, a non-zero error code is +returned. +

Errors

The pthread_sigmask function returns the following error +codes on error: +

EINVAL +: + how is not one of SIG_SETMASK, SIG_BLOCK, or + SIG_UNBLOCK +

+ +

+The pthread_kill function returns the following error codes on +error: +

EINVAL +: + signo is not a valid signal number or is unsupported.
+ ESRCH +: + the thread thread does not exist (e.g. it has already + terminated) +

+ +

+The sigwait function never returns an error. +

Author

Xavier Leroy <Xavier.Leroy@inria.fr> +

Modified by Ross Johnson for use with Pthreads-w32.

Notes

In any implementation, for sigwait to work reliably, the +signals being waited for must be blocked in all threads, not only in +the calling thread, since otherwise the POSIX semantics for signal +delivery do not guarantee that it’s the thread doing the sigwait +that will receive the signal. The best way to achieve this is to +block those signals before any threads are created, and never unblock +them in the program other than by calling sigwait. This works +because all threads inherit their initial sigmask from their creating +thread.

Bugs

Pthreads-w32 does not implement signals yet and so these +routines have almost no use except to prevent the compiler or linker +from complaining. pthread_kill is useful in determining if the +thread is a valid thread, but since many threads implementations +reuse thread IDs, the valid thread may no longer be the thread you +think it is, and so this method of determining thread validity is not +portable, and very risky. Pthreads-w32 from version 1.0.0 +onwards implements pseudo-unique thread IDs, so applications that use +this technique (but really shouldn't) have some protection.

Table of Contents

Name +
+
Synopsis +
+
Description +
+
Cancellation +
+
Return + Value +
+
Errors +
+
Author +
+
See + Also +
+
Notes +
+
Bugs +
+

+ + diff --git a/manual/pthread_mutex_init.html b/manual/pthread_mutex_init.html new file mode 100644 index 0000000..f9982cf --- /dev/null +++ b/manual/pthread_mutex_init.html @@ -0,0 +1,277 @@ + + + + + PTHREAD_MUTEX(3) manual page + + + + + + + +

POSIX Threads for Windows – REFERENCE - Pthreads-w32

Reference Index

Table of Contents

Name

pthread_mutex_init, pthread_mutex_lock, pthread_mutex_trylock, +pthread_mutex_timedlock, pthread_mutex_unlock, pthread_mutex_destroy +- operations on mutexes +

Synopsis

#include <pthread.h> +

#include <time.h>

pthread_mutex_t fastmutex = +PTHREAD_MUTEX_INITIALIZER; +

pthread_mutex_t recmutex = +PTHREAD_RECURSIVE_MUTEX_INITIALIZER; +

pthread_mutex_t errchkmutex = +PTHREAD_ERRORCHECK_MUTEX_INITIALIZER; +

pthread_mutex_t recmutex = +PTHREAD_RECURSIVE_MUTEX_INITIALIZER_NP; +

pthread_mutex_t errchkmutex = +PTHREAD_ERRORCHECK_MUTEX_INITIALIZER_NP; +

int pthread_mutex_init(pthread_mutex_t *mutex, +const pthread_mutexattr_t *mutexattr); +

int pthread_mutex_lock(pthread_mutex_t *mutex); +

int pthread_mutex_trylock(pthread_mutex_t *mutex); +

int pthread_mutex_timedlock(pthread_mutex_t *mutex, +const struct timespec *abs_timeout); +

int pthread_mutex_unlock(pthread_mutex_t *mutex); +

int pthread_mutex_destroy(pthread_mutex_t *mutex); +

Description

A mutex is a MUTual EXclusion device, and is useful for protecting +shared data structures from concurrent modifications, and +implementing critical sections and monitors. +

A mutex has two possible states: unlocked (not owned by any +thread), and locked (owned by one thread). A mutex can never be owned +by two different threads simultaneously. A thread attempting to lock +a mutex that is already locked by another thread is suspended until +the owning thread unlocks the mutex first. +

pthread_mutex_init initializes the mutex object pointed to +by mutex according to the mutex attributes specified in +mutexattr. If mutexattr is NULL, default +attributes are used instead. +

The type of a mutex determines whether it can be locked again by a +thread that already owns it. The default type is “normal”. See +pthread_mutexattr_init(3) +for more information on mutex attributes. +

Variables of type pthread_mutex_t can also be initialized +statically, using the constants PTHREAD_MUTEX_INITIALIZER (for +normal “fast” mutexes), PTHREAD_RECURSIVE_MUTEX_INITIALIZER +(for recursive mutexes), and PTHREAD_ERRORCHECK_MUTEX_INITIALIZER +(for error checking mutexes). In +the Pthreads-w32 implementation, an application should still +call pthread_mutex_destroy at some point to ensure that any +resources consumed by the mutex are released.

pthread_mutex_lock locks the given mutex. If the mutex is +currently unlocked, it becomes locked and owned by the calling +thread, and pthread_mutex_lock returns immediately. If the +mutex is already locked by another thread, pthread_mutex_lock +suspends the calling thread until the mutex is unlocked. +

If the mutex is already locked by the calling thread, the behavior +of pthread_mutex_lock depends on the type of the mutex. If the +mutex is of the “normal” type, the calling thread is suspended +until the mutex is unlocked, thus effectively causing the calling +thread to deadlock. If the mutex is of the ‘‘error checking’’ +type, pthread_mutex_lock returns immediately with the error +code EDEADLK. If the mutex is of the ‘‘recursive’’ +type, pthread_mutex_lock succeeds and returns immediately, +recording the number of times the calling thread has locked the +mutex. An equal number of pthread_mutex_unlock operations must +be performed before the mutex returns to the unlocked state. +

pthread_mutex_trylock behaves identically to +pthread_mutex_lock, except that it does not block the calling +thread if the mutex is already locked by another thread (or by the +calling thread in the case of a “normal” mutex). Instead, +pthread_mutex_trylock returns immediately with the error code +EBUSY. +

pthread_mutex_timedlock behaves identically to +pthread_mutex_lock, except that if it cannot acquire the lock +before the abs_timeout time, the call returns with the error +code ETIMEDOUT. If the mutex can be locked immediately it is, +and the abs_timeout parameter is ignored.

pthread_mutex_unlock unlocks the given mutex. The mutex is +assumed to be locked and owned by the calling thread on entrance to +pthread_mutex_unlock. If the mutex is of the “normal” +type, pthread_mutex_unlock always returns it to the unlocked +state. If it is of the ‘‘recursive’’ type, it decrements the +locking count of the mutex (number of pthread_mutex_lock +operations performed on it by the calling thread), and only when this +count reaches zero is the mutex actually unlocked. +

On ‘‘error checking’’ mutexes, pthread_mutex_unlock +actually checks at run-time that the mutex is locked on entrance, and +that it was locked by the same thread that is now calling +pthread_mutex_unlock. If these conditions are not met, an +error code is returned and the mutex remains unchanged. ‘‘Normal’’ +mutexes perform no such checks, thus allowing a locked mutex to be +unlocked by a thread other than its owner. This is non-portable +behavior and is not meant to be used as a feature.

pthread_mutex_destroy destroys a mutex object, freeing the +resources it might hold. The mutex must be unlocked on entrance.

Cancellation

None of the mutex functions is a cancellation point, not even +pthread_mutex_lock, in spite of the fact that it can suspend a +thread for arbitrary durations. This way, the status of mutexes at +cancellation points is predictable, allowing cancellation handlers to +unlock precisely those mutexes that need to be unlocked before the +thread stops executing. Consequently, threads using deferred +cancellation should never hold a mutex for extended periods of time. +

Async-signal Safety

The mutex functions are not async-signal safe. What this means is +that they should not be called from a signal handler. In particular, +calling pthread_mutex_lock or pthread_mutex_unlock from +a signal handler may deadlock the calling thread. +

Return Value

pthread_mutex_init always returns 0. The other mutex +functions return 0 on success and a non-zero error code on error. +

Errors

The pthread_mutex_lock function returns the following error +code on error: +

EINVAL +: + the mutex has not been properly initialized. +
+ EDEADLK +: + the mutex is already locked by the calling thread (‘‘error + checking’’ mutexes only). +

+ +

+The pthread_mutex_trylock function returns the following error +codes on error: +

EBUSY +: + the mutex could not be acquired because it was currently locked. +
+ EINVAL +: + the mutex has not been properly initialized. +

+ +

+The pthread_mutex_timedlock function returns the following +error codes on error: +

ETIMEDOUT +: + the mutex could not be acquired before the abs_timeout time + arrived. +
+ EINVAL +: + the mutex has not been properly initialized. +

+ +

+The pthread_mutex_unlock function returns the following error +code on error: +

EINVAL +: + the mutex has not been properly initialized. +
+ EPERM +: + the calling thread does not own the mutex (‘‘error checking’’ + mutexes only). +

+ +

+The pthread_mutex_destroy function returns the following error +code on error: +

EBUSY +: + the mutex is currently locked. +

+ +

+Author

Xavier Leroy <Xavier.Leroy@inria.fr> +

Modified by Ross Johnson for use with Pthreads-w32.

Example

A shared global variable x can be protected by a mutex as +follows: +

int x;
+pthread_mutex_t mut = PTHREAD_MUTEX_INITIALIZER;

+All accesses and modifications to x should be bracketed by +calls to pthread_mutex_lock and pthread_mutex_unlock as +follows: +

pthread_mutex_lock(&mut);
+/* operate on x */
+pthread_mutex_unlock(&mut);

Table of +Contents

Name +
+
Synopsis +
+
Description +
+
Cancellation +
+
Async-signal + Safety +
+
Return + Value +
+
Errors +
+
Author +
+
See + Also +
+
Example +
+

+ + diff --git a/manual/pthread_mutexattr_init.html b/manual/pthread_mutexattr_init.html new file mode 100644 index 0000000..f3df993 --- /dev/null +++ b/manual/pthread_mutexattr_init.html @@ -0,0 +1,157 @@ + + + + + PTHREAD_MUTEXATTR(3) manual page + + + + + + + +

POSIX Threads for Windows – REFERENCE - Pthreads-w32

Reference Index

Table of Contents

Name

pthread_mutexattr_init, pthread_mutexattr_destroy, +pthread_mutexattr_settype, pthread_mutexattr_gettype - mutex creation +attributes +

Synopsis

#include <pthread.h> +

int pthread_mutexattr_init(pthread_mutexattr_t *attr); +

int pthread_mutexattr_destroy(pthread_mutexattr_t *attr); +

int pthread_mutexattr_settype(pthread_mutexattr_t *attr, +int type); +

int pthread_mutexattr_gettype(const pthread_mutexattr_t *attr, +int *type); +

int pthread_mutexattr_setkind_np(pthread_mutexattr_t *attr, +int type); +

int pthread_mutexattr_getkind_np(const pthread_mutexattr_t +*attr, int *type); +

Description

Mutex attributes can be specified at mutex creation time, by +passing a mutex attribute object as second argument to +pthread_mutex_init(3) . +Passing NULL is equivalent to passing a mutex attribute object +with all attributes set to their default values. +

pthread_mutexattr_init initializes the mutex attribute +object attr and fills it with default values for the +attributes. +

pthread_mutexattr_destroy destroys a mutex attribute +object, which must not be reused until it is reinitialized.

The following mutex types are supported:

PTHREAD_MUTEX_NORMAL - for +‘‘fast’’ mutexes.

PTHREAD_MUTEX_RECURSIVE - for +‘‘recursive’’ mutexes.

PTHREAD_MUTEX_ERRORCHECK - for +‘‘error checking’’ mutexes.

The mutex type determines what happens if a thread attempts to +lock a mutex it already owns with pthread_mutex_lock(3) +. If the mutex is of the “normal” or “fast” type, +pthread_mutex_lock(3) +simply suspends the calling thread forever. If the mutex is of the +‘‘error checking’’ type, pthread_mutex_lock(3) +returns immediately with the error code EDEADLK. If the mutex +is of the ‘‘recursive’’ type, the call to +pthread_mutex_lock(3) +returns immediately with a success return code. The number of times +the thread owning the mutex has locked it is recorded in the mutex. +The owning thread must call pthread_mutex_unlock(3) +the same number of times before the mutex returns to the unlocked +state. +

The default mutex type is PTHREAD_MUTEX_NORMAL

Pthreads-w32 also recognises the following equivalent types +that are used by Linux:

PTHREAD_MUTEX_FAST_NP +– equivalent to PTHREAD_MUTEX_NORMAL

PTHREAD_MUTEX_RECURSIVE_NP

PTHREAD_MUTEX_ERRORCHECK_NP

pthread_mutexattr_settype sets the mutex type attribute in +attr to the value specified by type. +

pthread_mutexattr_gettype retrieves the current value of +the mutex kind attribute in attr and stores it in the location +pointed to by type. +

Pthreads-w32 also recognises the following equivalent +functions that are used in Linux:

pthread_mutexattr_setkind_np is an alias for +pthread_mutexattr_settype. +

pthread_mutexattr_getkind_np is +an alias for pthread_mutexattr_gettype. +

Return Value

pthread_mutexattr_init, pthread_mutexattr_destroy +and pthread_mutexattr_gettype always return 0. +

pthread_mutexattr_settype returns 0 on success and a +non-zero error code on error. +

Errors

On error, pthread_mutexattr_settype returns the following +error code: +

EINVAL +: + type is none of:
PTHREAD_MUTEX_NORMAL, + PTHREAD_MUTEX_FAST_NP,
PTHREAD_MUTEX_RECURSIVE, + PTHREAD_MUTEX_RECURSIVE_NP,
PTHREAD_MUTEX_ERRORCHECK, + PTHREAD_MUTEX_ERRORCHECK_NP +

+Author

Xavier Leroy <Xavier.Leroy@inria.fr> +

Modified by Ross Johnson for use with Pthreads-w32.

Notes

For speed, Pthreads-w32 never checks the thread ownership +of mutexes of type PTHREAD_MUTEX_NORMAL (or +PTHREAD_MUTEX_FAST_NP) when performing operations on the +mutex. It is therefore possible for one thread to lock such a mutex +and another to unlock it.

When developing code, it is a +common precaution to substitute the error checking type, and drop in +the normal type for release if the extra performance is required.

Table of Contents

Name +
+
Synopsis +
+
Description +
+
Return + Value +
+
Errors +
+
Author +
+
See + Also
+
Notes
+

+ + diff --git a/manual/pthread_mutexattr_setpshared.html b/manual/pthread_mutexattr_setpshared.html new file mode 100644 index 0000000..25bf9f6 --- /dev/null +++ b/manual/pthread_mutexattr_setpshared.html @@ -0,0 +1,151 @@ + + + + + "PTHREAD_MUTEXATTR_GETPSHARED"(P) manual page + + + + + + + +

POSIX Threads for Windows – REFERENCE - Pthreads-w32

Reference Index

Table of Contents

Name

pthread_mutexattr_getpshared, pthread_mutexattr_setpshared - get +and set the process-shared attribute +

Synopsis

#include <pthread.h> +

int pthread_mutexattr_getpshared(const pthread_mutexattr_t * +restrict attr, int *restrict pshared); +
int pthread_mutexattr_setpshared(pthread_mutexattr_t *attr, +int pshared); +

Description

The pthread_mutexattr_getpshared function shall obtain the +value of the process-shared attribute from the attributes +object referenced by attr. The pthread_mutexattr_setpshared +function shall set the process-shared attribute in an +initialized attributes object referenced by attr. +

The process-shared attribute is set to +PTHREAD_PROCESS_SHARED to permit a mutex to be operated upon +by any thread that has access to the memory where the mutex is +allocated, even if the mutex is allocated in memory that is shared by +multiple processes. If the process-shared attribute is +PTHREAD_PROCESS_PRIVATE, the mutex shall only be operated upon +by threads created within the same process as the thread that +initialized the mutex; if threads of differing processes attempt to +operate on such a mutex, the behavior is undefined. The default value +of the attribute shall be PTHREAD_PROCESS_PRIVATE. +

Pthreads-w32 defines _POSIX_THREAD_PROCESS_SHARED in +pthread.h as -1 to indicate that these routines are implemented but +the process shared option is not supported.

Return Value

Upon successful completion, pthread_mutexattr_setpshared +shall return zero; otherwise, an error number shall be returned to +indicate the error. +

Upon successful completion, pthread_mutexattr_getpshared +shall return zero and store the value of the process-shared +attribute of attr into the object referenced by the pshared +parameter. Otherwise, an error number shall be returned to indicate +the error. +

Errors

The pthread_mutexattr_getpshared and +pthread_mutexattr_setpshared functions may fail if: +

EINVAL +: + The value specified by attr is invalid. +

+The pthread_mutexattr_setpshared function may fail if: +

EINVAL +: + The new value specified for the attribute is outside the range of + legal values for that attribute. +
+ ENOTSUP +: + The new value specified for the attribute is PTHREAD_PROCESS_SHARED. +

+These functions shall not return an error code of [EINTR]. +

The following sections are informative. +

Examples

None. +

Application Usage

None. +

Rationale

None. +

Future Directions

None. +

Copyright

Modified by Ross Johnson for use with Pthreads-w32.

Table of Contents

Name +
+
Synopsis +
+
Description +
+
Return + Value +
+
Errors +
+
Examples +
+
Application + Usage +
+
Rationale +
+
Future + Directions +
+
See + Also +
+
Copyright +
+

+ + diff --git a/manual/pthread_num_processors_np.html b/manual/pthread_num_processors_np.html new file mode 100644 index 0000000..0509410 --- /dev/null +++ b/manual/pthread_num_processors_np.html @@ -0,0 +1,57 @@ + + + + + PTHREAD_NUM_PROCESSORS_NP manual page + + + + + + + +

POSIX Threads for Windows – REFERENCE - Pthreads-w32

Reference Index

Table of Contents

Name

pthread_num_processors_np – get the +number of processors (CPUs) in use by the process

Synopsis

#include <pthread.h> +

int pthread_num_processors_np(void);

Description

pthread_num_processors_np returns the number of processors +in the system. This implementation actually returns the number of +processors available to the process, which can be a lower number than +the system's number, depending on the process's affinity mask.

Cancellation

None.

Return Value

pthread_num_processors_np returns the number of processors +currently available to the process.

Errors

None.

Author

Ross Johnson for use with Pthreads-w32.

Table of Contents

Name +
+
Synopsis +
+
Description +
+
Cancellation +
+
Return + Value +
+
Errors +
+
Author +
+

+ + diff --git a/manual/pthread_once.html b/manual/pthread_once.html new file mode 100644 index 0000000..8caa864 --- /dev/null +++ b/manual/pthread_once.html @@ -0,0 +1,87 @@ + + + + + PTHREAD_ONCE(3) manual page + + + + + + + +

POSIX Threads for Windows – REFERENCE - Pthreads-w32

Reference Index

Table of Contents

Name

pthread_once - once-only initialization +

Synopsis

#include <pthread.h> +

pthread_once_t once_control = PTHREAD_ONCE_INIT; +

int pthread_once(pthread_once_t *once_control, +void (*init_routine) (void)); +

Description

The purpose of pthread_once is to ensure that a piece of +initialization code is executed at most once. The once_control +argument points to a static or extern variable statically initialized +to PTHREAD_ONCE_INIT. +

The first time pthread_once is called with a given +once_control argument, it calls init_routine with no +argument and changes the value of the once_control variable to +record that initialization has been performed. Subsequent calls to +pthread_once with the same once_control argument do +nothing. +

Cancellation

While pthread_once is not a cancellation point, +init_routine can be. The required effect on once_control +of a cancellation inside the init_routine is to leave it as if +pthread_once had not been called.

Pthreads-w32 handles init_routine cancellation by +making any threads, that may be waiting on once_control, +re-compete along with any newly arriving threads in the re-running of +init_routine.

Return Value

pthread_once +returns 0 on success, or an error code on failure.

Errors

The pthread_once function returns the following error code +on error: +

EINVAL +

+ +

+The once_control or init_routine parameter is NULL.

Author

Xavier Leroy <Xavier.Leroy@inria.fr> +

Modified by Ross Johnson for use with Pthreads-w32.

Table of Contents

Name +
+
Synopsis +
+
Description +
+
Cancellation +
+
Return + Value +
+
Errors +
+
Author +
+

+ + diff --git a/manual/pthread_rwlock_init.html b/manual/pthread_rwlock_init.html new file mode 100644 index 0000000..530df93 --- /dev/null +++ b/manual/pthread_rwlock_init.html @@ -0,0 +1,193 @@ + + + + + "PTHREAD_RWLOCK_DESTROY"(P) manual page + + + + + + + +

POSIX Threads for Windows – REFERENCE - Pthreads-w32

Reference Index

Table of Contents

Name

pthread_rwlock_destroy, pthread_rwlock_init - destroy and +initialize a read-write lock object +

Synopsis

#include <pthread.h> +

pthread_wrlock_t rwlock = +PTHREAD_RWLOCK_INITIALIZER;

int pthread_rwlock_destroy(pthread_rwlock_t *rwlock); +
int pthread_rwlock_init(pthread_rwlock_t *restrict rwlock, +const pthread_rwlockattr_t *restrict attr); +

Description

The pthread_rwlock_destroy function shall destroy the +read-write lock object referenced by rwlock and release any +resources used by the lock. The effect of subsequent use of the lock +is undefined until the lock is reinitialized by another call to +pthread_rwlock_init. An implementation may cause +pthread_rwlock_destroy to set the object referenced by rwlock +to an invalid value. Results are undefined if pthread_rwlock_destroy +is called when any thread holds rwlock. Attempting to destroy +an uninitialized read-write lock results in undefined behavior. +

The pthread_rwlock_init function shall allocate any +resources required to use the read-write lock referenced by rwlock +and initializes the lock to an unlocked state with attributes +referenced by attr. If attr is NULL, the default +read-write lock attributes shall be used; the effect is the same as +passing the address of a default read-write lock attributes object. +Once initialized, the lock can be used any number of times without +being reinitialized. Results are undefined if pthread_rwlock_init +is called specifying an already initialized read-write lock. Results +are undefined if a read-write lock is used without first being +initialized. +

If the pthread_rwlock_init function fails, rwlock +shall not be initialized and the contents of rwlock are +undefined. +

Pthreads-w32 supports statically initialized rwlock +objects using PTHREAD_RWLOCK_INITIALIZER. +An application should still call pthread_rwlock_destroy at +some point to ensure that any resources consumed by the read/write +lock are released.

Only the object referenced by rwlock may be used for +performing synchronization. The result of referring to copies of that +object in calls to pthread_rwlock_destroy , +pthread_rwlock_rdlock , pthread_rwlock_timedrdlock , +pthread_rwlock_timedwrlock , pthread_rwlock_tryrdlock , +pthread_rwlock_trywrlock , pthread_rwlock_unlock , or +pthread_rwlock_wrlock is undefined. +

Pthreads-w32 defines _POSIX_READER_WRITER_LOCKS in +pthread.h as 200112L to indicate that the reader/writer routines are +implemented and may be used.

Return Value

If successful, the pthread_rwlock_destroy and +pthread_rwlock_init functions shall return zero; otherwise, an +error number shall be returned to indicate the error. +

The [EBUSY] and [EINVAL] error checks, if implemented, act as if +they were performed immediately at the beginning of processing for +the function and caused an error return prior to modifying the state +of the read-write lock specified by rwlock. +

Errors

The pthread_rwlock_destroy function may fail if: +

EBUSY +: + The implementation has detected an attempt to destroy the object + referenced by rwlock while it is locked. +
+ EINVAL +: + The value specified by rwlock is invalid. +

+The pthread_rwlock_init function shall fail if: +

EAGAIN +: + The system lacked the necessary resources (other than memory) to + initialize another read-write lock. +
+ ENOMEM +: + Insufficient memory exists to initialize the read-write lock. +; +

+

+The pthread_rwlock_init function may fail if: +

EINVAL +: + The value specified by attr is invalid. +

+These functions shall not return an error code of [EINTR]. +

The following sections are informative. +

Examples

None. +

Application Usage

Applications using these and related read-write lock functions may +be subject to priority inversion, as discussed in the Base +Definitions volume of IEEE Std 1003.1-2001, Section 3.285, +Priority Inversion. +

Rationale

None. +

Future Directions

None. +

Copyright

Modified by Ross Johnson for use with Pthreads-w32.

Table of Contents

Name +
+
Synopsis +
+
Description +
+
Return + Value +
+
Errors +
+
Examples +
+
Application + Usage +
+
Rationale +
+
Future + Directions +
+
See + Also +
+
Copyright +
+

+ + diff --git a/manual/pthread_rwlock_rdlock.html b/manual/pthread_rwlock_rdlock.html new file mode 100644 index 0000000..3b63f25 --- /dev/null +++ b/manual/pthread_rwlock_rdlock.html @@ -0,0 +1,168 @@ + + + + + "PTHREAD_RWLOCK_RDLOCK"(P) manual page + + + + + + + +

POSIX Threads for Windows – REFERENCE - Pthreads-w32

Reference Index

Table of Contents

Name

pthread_rwlock_rdlock, pthread_rwlock_tryrdlock - lock a +read-write lock object for reading +

Synopsis

#include <pthread.h> +

int pthread_rwlock_rdlock(pthread_rwlock_t *rwlock); +
int pthread_rwlock_tryrdlock(pthread_rwlock_t *rwlock); + +

Description

The pthread_rwlock_rdlock function shall apply a read lock +to the read-write lock referenced by rwlock. The calling +thread acquires the read lock if a writer does not hold the lock and +there are no writers blocked on the lock. +

Pthreads-win32 does not prefer either writers or readers in +acquiring the lock – all threads enter a single prioritised FIFO +queue. While this may not be optimally efficient for some +applications, it does ensure that one type does not starve the other.

A thread may hold multiple concurrent read locks on rwlock +(that is, successfully call the pthread_rwlock_rdlock function +n times). If so, the application shall ensure that the thread +performs matching unlocks (that is, it calls the +pthread_rwlock_unlock(3) +function n times). +

The pthread_rwlock_tryrdlock function shall apply a read +lock as in the pthread_rwlock_rdlock function, with the +exception that the function shall fail if the equivalent +pthread_rwlock_rdlock call would have blocked the calling +thread. In no case shall the pthread_rwlock_tryrdlock function +ever block; it always either acquires the lock or fails and returns +immediately. +

Results are undefined if any of these functions are called with an +uninitialized read-write lock. +

Pthreads-w32 does not detect deadlock if the thread already +owns the lock for writing.

Pthreads-w32 defines _POSIX_READER_WRITER_LOCKS in +pthread.h as 200112L to indicate that the reader/writer routines are +implemented and may be used.

Return Value

If successful, the pthread_rwlock_rdlock function shall +return zero; otherwise, an error number shall be returned to indicate +the error. +

The pthread_rwlock_tryrdlock function shall return zero if +the lock for reading on the read-write lock object referenced by +rwlock is acquired. Otherwise, an error number shall be +returned to indicate the error. +

Errors

The pthread_rwlock_tryrdlock function shall fail if: +

EBUSY +: + The read-write lock could not be acquired for reading because a + writer holds the lock or a writer with the appropriate priority was + blocked on it. +

+The pthread_rwlock_rdlock and pthread_rwlock_tryrdlock +functions may fail if: +

EINVAL +: + The value specified by rwlock does not refer to an + initialized read-write lock object. +
+ EAGAIN +: + The read lock could not be acquired because the maximum number of + read locks for rwlock has been exceeded. +

+These functions shall not return an error code of [EINTR]. +

The following sections are informative. +

Examples

None. +

Application Usage

Applications using these functions may be subject to priority +inversion, as discussed in the Base Definitions volume of +IEEE Std 1003.1-2001, Section 3.285, Priority Inversion. +

Rationale

None. +

Future Directions

None. +

Copyright

Modified by Ross Johnson for use with Pthreads-w32.

Table of Contents

Name +
+
Synopsis +
+
Description +
+
Return + Value +
+
Errors +
+
Examples +
+
Application + Usage +
+
Rationale +
+
Future + Directions +
+
See + Also +
+
Copyright +
+

+ + diff --git a/manual/pthread_rwlock_timedrdlock.html b/manual/pthread_rwlock_timedrdlock.html new file mode 100644 index 0000000..1b9ca63 --- /dev/null +++ b/manual/pthread_rwlock_timedrdlock.html @@ -0,0 +1,156 @@ + + + + + "PTHREAD_RWLOCK_TIMEDRDLOCK"(P) manual page + + + + + + + +

POSIX Threads for Windows – REFERENCE - Pthreads-w32

Reference Index

Table of Contents

Name

pthread_rwlock_timedrdlock - lock a read-write lock for reading +

Synopsis

#include <pthread.h>
#include <time.h> +

int pthread_rwlock_timedrdlock(pthread_rwlock_t *restrict +rwlock, const struct timespec *restrict abs_timeout); + +

Description

The pthread_rwlock_timedrdlock function shall apply a read +lock to the read-write lock referenced by rwlock as in the +pthread_rwlock_rdlock(3) +function. However, if the lock cannot be acquired without waiting for +other threads to unlock the lock, this wait shall be terminated when +the specified timeout expires. The timeout shall expire when the +absolute time specified by abs_timeout passes, as measured by +the clock on which timeouts are based (that is, when the value of +that clock equals or exceeds abs_timeout), or if the absolute +time specified by abs_timeout has already been passed at the +time of the call. +

The timespec data type is defined in the <time.h> +header. Under no circumstances shall the function fail with a timeout +if the lock can be acquired immediately. The validity of the +abs_timeout parameter need not be checked if the lock can be +immediately acquired. +

The calling thread may deadlock if at the time the call is made it +holds a write lock on rwlock. The results are undefined if +this function is called with an uninitialized read-write lock. +

Pthreads-w32 defines _POSIX_READER_WRITER_LOCKS in +pthread.h as 200112L to indicate that the reader/writer routines are +implemented and may be used.

Return Value

The pthread_rwlock_timedrdlock function shall return zero +if the lock for reading on the read-write lock object referenced by +rwlock is acquired. Otherwise, an error number shall be +returned to indicate the error. +

Errors

The pthread_rwlock_timedrdlock function shall fail if: +

ETIMEDOUT +: + The lock could not be acquired before the specified timeout expired. +

+The pthread_rwlock_timedrdlock function may fail if: +

EAGAIN +: + The read lock could not be acquired because the maximum number of + read locks for lock would be exceeded. +
+ EINVAL +: + The value specified by rwlock does not refer to an + initialized read-write lock object, or the abs_timeout + nanosecond value is less than zero or greater than or equal to 1000 + million. +

+This function shall not return an error code of [EINTR]. +

The following sections are informative. +

Examples

None. +

Application Usage

Applications using this function may be subject to priority +inversion, as discussed in the Base Definitions volume of +IEEE Std 1003.1-2001, Section 3.285, Priority Inversion. +

Rationale

None. +

Future Directions

None. +

Copyright

Modified by Ross Johnson for use with Pthreads-w32.

Table of Contents

Name +
+
Synopsis +
+
Description +
+
Return + Value +
+
Errors +
+
Examples +
+
Application + Usage +
+
Rationale +
+
Future + Directions +
+
See + Also +
+
Copyright +
+

+ + diff --git a/manual/pthread_rwlock_timedwrlock.html b/manual/pthread_rwlock_timedwrlock.html new file mode 100644 index 0000000..0213bab --- /dev/null +++ b/manual/pthread_rwlock_timedwrlock.html @@ -0,0 +1,150 @@ + + + + + "PTHREAD_RWLOCK_TIMEDWRLOCK"(P) manual page + + + + + + + +

POSIX Threads for Windows – REFERENCE - Pthreads-w32

Reference Index

Table of Contents

Name

pthread_rwlock_timedwrlock - lock a read-write lock for writing +

Synopsis

#include <pthread.h>
#include <time.h> +

int pthread_rwlock_timedwrlock(pthread_rwlock_t *restrict +rwlock, const struct timespec *restrict abs_timeout); + +

Description

The pthread_rwlock_timedwrlock function shall apply a write +lock to the read-write lock referenced by rwlock as in the +pthread_rwlock_wrlock(3) +function. However, if the lock cannot be acquired without waiting for +other threads to unlock the lock, this wait shall be terminated when +the specified timeout expires. The timeout shall expire when the +absolute time specified by abs_timeout passes, as measured by +the clock on which timeouts are based (that is, when the value of +that clock equals or exceeds abs_timeout), or if the absolute +time specified by abs_timeout has already been passed at the +time of the call. +

The calling thread may deadlock if at the time the call is made it +holds the read-write lock. The results are undefined if this function +is called with an uninitialized read-write lock. +

Pthreads-w32 defines _POSIX_READER_WRITER_LOCKS in +pthread.h as 200112L to indicate that the reader/writer routines are +implemented and may be used.

Return Value

The pthread_rwlock_timedwrlock function shall return zero +if the lock for writing on the read-write lock object referenced by +rwlock is acquired. Otherwise, an error number shall be +returned to indicate the error. +

Errors

The pthread_rwlock_timedwrlock function shall fail if: +

ETIMEDOUT +: + The lock could not be acquired before the specified timeout expired. +

+The pthread_rwlock_timedwrlock function may fail if: +

EINVAL +: + The value specified by rwlock does not refer to an initialized + read-write lock object, or the abs_timeout nanosecond value + is less than zero or greater than or equal to 1000 million. +

+This function shall not return an error code of [EINTR]. +

The following sections are informative. +

Examples

None. +

Application Usage

Applications using this function may be subject to priority +inversion, as discussed in the Base Definitions volume of +IEEE Std 1003.1-2001, Section 3.285, Priority Inversion. +

Rationale

None. +

Future Directions

None. +

Copyright

Modified by Ross Johnson for use with Pthreads-w32.

Table of Contents

Name +
+
Synopsis +
+
Description +
+
Return + Value +
+
Errors +
+
Examples +
+
Application + Usage +
+
Rationale +
+
Future + Directions +
+
See + Also +
+
Copyright +
+

+ + diff --git a/manual/pthread_rwlock_unlock.html b/manual/pthread_rwlock_unlock.html new file mode 100644 index 0000000..09725cc --- /dev/null +++ b/manual/pthread_rwlock_unlock.html @@ -0,0 +1,141 @@ + + + + + "PTHREAD_RWLOCK_UNLOCK"(P) manual page + + + + + + + +

POSIX Threads for Windows – REFERENCE - Pthreads-w32

Reference Index

Table of Contents

Name

pthread_rwlock_unlock - unlock a read-write lock object +

Synopsis

#include <pthread.h> +

int pthread_rwlock_unlock(pthread_rwlock_t *rwlock); + +

Description

The pthread_rwlock_unlock function shall release a lock +held on the read-write lock object referenced by rwlock. +Results are undefined if the read-write lock rwlock is not +held by the calling thread. +

If this function is called to release a read lock from the +read-write lock object and there are other read locks currently held +on this read-write lock object, the read-write lock object remains in +the read locked state. If this function releases the last read lock +for this read-write lock object, the read-write lock object shall be +put in the unlocked state with no owners. +

If this function is called to release a write lock for this +read-write lock object, the read-write lock object shall be put in +the unlocked state. +

Results are undefined if any of these functions are called with an +uninitialized read-write lock. +

Pthreads-w32 defines _POSIX_READER_WRITER_LOCKS in +pthread.h as 200112L to indicate that the reader/writer routines are +implemented and may be used.

Return Value

If successful, the pthread_rwlock_unlock function shall +return zero; otherwise, an error number shall be returned to indicate +the error. +

Errors

The pthread_rwlock_unlock function may fail if: +

EINVAL +: + The value specified by rwlock does not refer to an + initialized read-write lock object. +; +

+

+The pthread_rwlock_unlock function shall not return an error +code of [EINTR]. +

The following sections are informative. +

Examples

None. +

Application Usage

None. +

Rationale

None. +

Future Directions

None. +

Copyright

Modified by Ross Johnson for use with Pthreads-w32.

Table of Contents

Name +
+
Synopsis +
+
Description +
+
Return + Value +
+
Errors +
+
Examples +
+
Application + Usage +
+
Rationale +
+
Future + Directions +
+
See + Also +
+
Copyright +
+

+ + diff --git a/manual/pthread_rwlock_wrlock.html b/manual/pthread_rwlock_wrlock.html new file mode 100644 index 0000000..02b3a19 --- /dev/null +++ b/manual/pthread_rwlock_wrlock.html @@ -0,0 +1,153 @@ + + + + + "PTHREAD_RWLOCK_TRYWRLOCK"(P) manual page + + + + + + + +

POSIX Threads for Windows – REFERENCE - Pthreads-w32

Reference Index

Table of Contents

Name

pthread_rwlock_trywrlock, pthread_rwlock_wrlock - lock a +read-write lock object for writing +

Synopsis

#include <pthread.h> +

int pthread_rwlock_trywrlock(pthread_rwlock_t *rwlock); +
int pthread_rwlock_wrlock(pthread_rwlock_t *rwlock); + +

Description

The pthread_rwlock_trywrlock function shall apply a write +lock like the pthread_rwlock_wrlock function, with the +exception that the function shall fail if any thread currently holds +rwlock (for reading or writing). +

The pthread_rwlock_wrlock function shall apply a write lock +to the read-write lock referenced by rwlock. The calling +thread acquires the write lock if no other thread (reader or writer) +holds the read-write lock rwlock. Otherwise, the thread shall +block until it can acquire the lock. The calling thread may deadlock +if at the time the call is made it holds the read-write lock (whether +a read or write lock). +

Results are undefined if any of these functions are called with an +uninitialized read-write lock. +

Pthreads-w32 defines _POSIX_READER_WRITER_LOCKS in +pthread.h as 200112L to indicate that the reader/writer routines are +implemented and may be used.

Return Value

The pthread_rwlock_trywrlock function shall return zero if +the lock for writing on the read-write lock object referenced by +rwlock is acquired. Otherwise, an error number shall be +returned to indicate the error. +

If successful, the pthread_rwlock_wrlock function shall +return zero; otherwise, an error number shall be returned to indicate +the error. +

Errors

The pthread_rwlock_trywrlock function shall fail if: +

EBUSY +: + The read-write lock could not be acquired for writing because it was + already locked for reading or writing. +

+The pthread_rwlock_trywrlock and pthread_rwlock_wrlock +functions may fail if: +

EINVAL +: + The value specified by rwlock does not refer to an + initialized read-write lock object. +

+These functions shall not return an error code of [EINTR]. +

The following sections are informative. +

Examples

None. +

Application Usage

Applications using these functions may be subject to priority +inversion, as discussed in the Base Definitions volume of +IEEE Std 1003.1-2001, Section 3.285, Priority Inversion. +

Rationale

None. +

Future Directions

None. +

Copyright

Modified by Ross Johnson for use with Pthreads-w32.

Table of Contents

Name +
+
Synopsis +
+
Description +
+
Return + Value +
+
Errors +
+
Examples +
+
Application + Usage +
+
Rationale +
+
Future + Directions +
+
See + Also +
+
Copyright +
+

+ + diff --git a/manual/pthread_rwlockattr_init.html b/manual/pthread_rwlockattr_init.html new file mode 100644 index 0000000..67da876 --- /dev/null +++ b/manual/pthread_rwlockattr_init.html @@ -0,0 +1,141 @@ + + + + + "PTHREAD_RWLOCKATTR_DESTROY"(P) manual page + + + + + + + +

POSIX Threads for Windows – REFERENCE - Pthreads-w32

Reference Index

Table of Contents

Name

pthread_rwlockattr_destroy, pthread_rwlockattr_init - destroy and +initialize the read-write lock attributes object +

Synopsis

#include <pthread.h> +

int pthread_rwlockattr_destroy(pthread_rwlockattr_t *attr); +
int pthread_rwlockattr_init(pthread_rwlockattr_t *attr); + +

Description

The pthread_rwlockattr_destroy function shall destroy a +read-write lock attributes object. A destroyed attr attributes +object can be reinitialized using pthread_rwlockattr_init ; +the results of otherwise referencing the object after it has been +destroyed are undefined. An implementation may cause +pthread_rwlockattr_destroy to set the object referenced by +attr to an invalid value. +

The pthread_rwlockattr_init function shall initialize a +read-write lock attributes object attr with the default value +for all of the attributes defined by the implementation. +

Results are undefined if pthread_rwlockattr_init is called +specifying an already initialized attr attributes object. +

After a read-write lock attributes object has been used to +initialize one or more read-write locks, any function affecting the +attributes object (including destruction) shall not affect any +previously initialized read-write locks. +

Pthreads-w32 defines _POSIX_READER_WRITER_LOCKS in +pthread.h as 200112L to indicate that the reader/writer routines are +implemented and may be used.

Return Value

If successful, the pthread_rwlockattr_destroy and +pthread_rwlockattr_init functions shall return zero; +otherwise, an error number shall be returned to indicate the error. +

Errors

The pthread_rwlockattr_destroy function may fail if: +

EINVAL +: + The value specified by attr is invalid. +

+The pthread_rwlockattr_init function shall fail if: +

ENOMEM +: + Insufficient memory exists to initialize the read-write lock + attributes object. +

+These functions shall not return an error code of [EINTR]. +

The following sections are informative. +

Examples

None. +

Application Usage

None. +

Rationale

None. +

Future Directions

None. +

Copyright

Modified by Ross Johnson for use with Pthreads-w32.

Table of Contents

Name +
+
Synopsis +
+
Description +
+
Return + Value +
+
Errors +
+
Examples +
+
Application + Usage +
+
Rationale +
+
Future + Directions +
+
See + Also +
+
Copyright +
+

+ + diff --git a/manual/pthread_rwlockattr_setpshared.html b/manual/pthread_rwlockattr_setpshared.html new file mode 100644 index 0000000..9db6f4c --- /dev/null +++ b/manual/pthread_rwlockattr_setpshared.html @@ -0,0 +1,160 @@ + + + + + "PTHREAD_RWLOCKATTR_GETPSHARED"(P) manual page + + + + + + + +

POSIX Threads for Windows – REFERENCE - Pthreads-w32

Reference Index

Table of Contents

Name

pthread_rwlockattr_getpshared, pthread_rwlockattr_setpshared - get +and set the process-shared attribute of the read-write lock +attributes object +

Synopsis

#include <pthread.h> +

int pthread_rwlockattr_getpshared(const pthread_rwlockattr_t * +restrict attr, int *restrict pshared); +
int pthread_rwlockattr_setpshared(pthread_rwlockattr_t *attr, +int pshared); +

Description

The pthread_rwlockattr_getpshared function shall obtain the +value of the process-shared attribute from the initialized +attributes object referenced by attr. The +pthread_rwlockattr_setpshared function shall set the +process-shared attribute in an initialized attributes object +referenced by attr. +

The process-shared attribute shall be set to +PTHREAD_PROCESS_SHARED to permit a read-write lock to be +operated upon by any thread that has access to the memory where the +read-write lock is allocated, even if the read-write lock is +allocated in memory that is shared by multiple processes. If the +process-shared attribute is PTHREAD_PROCESS_PRIVATE, +the read-write lock shall only be operated upon by threads created +within the same process as the thread that initialized the read-write +lock; if threads of differing processes attempt to operate on such a +read-write lock, the behavior is undefined. The default value of the +process-shared attribute shall be PTHREAD_PROCESS_PRIVATE. +

Pthreads-w32 defines _POSIX_THREAD_PROCESS_SHARED in +pthread.h as -1 to indicate that these routines are implemented but +they do not support the process shared option.

Additional attributes, their default values, and the names of the +associated functions to get and set those attribute values are +implementation-defined. +

Pthreads-w32 defines _POSIX_READER_WRITER_LOCKS in +pthread.h as 200112L to indicate that the reader/writer routines are +implemented and may be used.

Return Value

Upon successful completion, the pthread_rwlockattr_getpshared +function shall return zero and store the value of the process-shared +attribute of attr into the object referenced by the pshared +parameter. Otherwise, an error number shall be returned to indicate +the error. +

If successful, the pthread_rwlockattr_setpshared function +shall return zero; otherwise, an error number shall be returned to +indicate the error. +

Errors

The pthread_rwlockattr_getpshared and +pthread_rwlockattr_setpshared functions may fail if: +

EINVAL +: + The value specified by attr is invalid. +

+The pthread_rwlockattr_setpshared function may fail if: +

EINVAL +: + The new value specified for the attribute is outside the range of + legal values for that attribute. +
+ ENOTSUP +: + The new value specified for the attribute is PTHREAD_PROCESS_SHARED. +

+These functions shall not return an error code of [EINTR]. +

The following sections are informative. +

Examples

None. +

Application Usage

None. +

Rationale

None. +

Future Directions

None. +

Copyright

Modified by Ross Johnson for use with Pthreads-w32.

Table of Contents

Name +
+
Synopsis +
+
Description +
+
Return + Value +
+
Errors +
+
Examples +
+
Application + Usage +
+
Rationale +
+
Future + Directions +
+
See + Also +
+
Copyright +
+

+ + diff --git a/manual/pthread_self.html b/manual/pthread_self.html new file mode 100644 index 0000000..82e16ea --- /dev/null +++ b/manual/pthread_self.html @@ -0,0 +1,70 @@ + + + + + PTHREAD_SELF(3) manual page + + + + + + + +

POSIX Threads for Windows – REFERENCE - Pthreads-w32

Reference Index

Table of Contents

Name

pthread_self - return identifier of current thread +

Synopsis

#include <pthread.h> +

pthread_t pthread_self(void); +

Description

pthread_self return the thread identifier for the calling +thread. +

Pthreads-w32 also provides support for Win32 native +threads to interact with POSIX threads through the pthreads API. +Whereas all threads created via a call to pthread_create have a POSIX +thread ID and thread state, the library ensures that any Win32 native +threads that interact through the Pthreads API also generate a POSIX +thread ID and thread state when and if necessary. This provides full +reciprocity between Win32 and POSIX +threads. Win32 native threads that generate a POSIX thread ID and +state are treated by the library as having been created with the +PTHREAD_CREATE_DETACHED attribute.

Any Win32 native thread may call pthread_self directly to +return it's POSIX thread identifier. The ID and state will be +generated if it does not already exist. Win32 native threads do not +need to call pthread_self before calling Pthreads-w32 routines +unless that routine requires a pthread_t parameter.

Author

Xavier Leroy <Xavier.Leroy@inria.fr> +

Modified by Ross Johnson for use with Pthreads-w32.

Name

pthread_cancel, pthread_setcancelstate, pthread_setcanceltype, +pthread_testcancel - thread cancellation +

Synopsis

#include <pthread.h> +

int pthread_cancel(pthread_t thread); +

int pthread_setcancelstate(int state, int +*oldstate); +

int pthread_setcanceltype(int type, int +*oldtype); +

void pthread_testcancel(void); +

Description

pthread_cancel sends a cancellation request to the thread +denoted by the thread argument. +

pthread_join(3) +
pthread_cond_wait(3) +
pthread_cond_timedwait(3) +
pthread_testcancel(3) +
sem_wait(3)
sem_timedwait(3) +
sigwait(3) (not supported under +Pthreads-w32)

Pthreads-w32 provides two functions to enable additional +cancellation points to be created in user functions that block on +Win32 HANDLEs:

pthreadCancelableWait() +
pthreadCancelableTimedWait()

All other POSIX threads functions are guaranteed not to be +cancellation points. That is, they never perform cancellation in +deferred cancellation mode. +

Return Value

pthread_cancel, pthread_setcancelstate and +pthread_setcanceltype return 0 on success and a non-zero error +code on error. +

Errors

pthread_cancel returns the following error code on error: +

ESRCH +: + no thread could be found corresponding to that specified by the + thread ID. +

+ +

+pthread_setcancelstate returns the following error code on +error: +

EINVAL +: + the state argument is not +

+ +

+PTHREAD_CANCEL_ENABLE nor PTHREAD_CANCEL_DISABLE +

pthread_setcanceltype returns the following error code on +error: +

EINVAL +: + the type argument is not +

+ +

+PTHREAD_CANCEL_DEFERRED nor PTHREAD_CANCEL_ASYNCHRONOUS +

Author

Xavier Leroy <Xavier.Leroy@inria.fr> +

Modified by Ross Johnson for use with Pthreads-w32.

Bugs

+

pthread_setcanceltype(PTHREAD_CANCEL_ASYNCHRONOUS, &oldCancelType);
+read(fd, buffer, length);
+pthread_setcanceltype(oldCancelType, NULL);

Table of Contents

Name +
+
Synopsis +
+
Description +
+
Return + Value +
+
Errors +
+
Author +
+
See + Also +
+
Bugs +
+

+ + diff --git a/manual/pthread_setcanceltype.html b/manual/pthread_setcanceltype.html new file mode 100644 index 0000000..935ed82 --- /dev/null +++ b/manual/pthread_setcanceltype.html @@ -0,0 +1,207 @@ + + + + + PTHREAD_CANCEL(3) manual page + + + + + + + +

POSIX Threads for Windows – REFERENCE - Pthreads-w32

Reference Index

Table of Contents

Name

pthread_cancel, pthread_setcancelstate, pthread_setcanceltype, +pthread_testcancel - thread cancellation +

Synopsis

#include <pthread.h> +

int pthread_cancel(pthread_t thread); +

int pthread_setcancelstate(int state, int +*oldstate); +

int pthread_setcanceltype(int type, int +*oldtype); +

void pthread_testcancel(void); +

Description

pthread_cancel sends a cancellation request to the thread +denoted by the thread argument. +

Pthreads-w32 provides two functions to enable additional +cancellation points to be created in user functions that block on +Win32 HANDLEs:

pthreadCancelableWait() +
pthreadCancelableTimedWait()

All other POSIX threads functions are guaranteed not to be +cancellation points. That is, they never perform cancellation in +deferred cancellation mode. +

Return Value

pthread_cancel, pthread_setcancelstate and +pthread_setcanceltype return 0 on success and a non-zero error +code on error. +

Errors

pthread_cancel returns the following error code on error: +

ESRCH +: + no thread could be found corresponding to that specified by the + thread ID. +

+ +

+pthread_setcancelstate returns the following error code on +error: +

EINVAL +: + the state argument is not +

+ +

+PTHREAD_CANCEL_ENABLE nor PTHREAD_CANCEL_DISABLE +

pthread_setcanceltype returns the following error code on +error: +

EINVAL +: + the type argument is not +

+ +

+PTHREAD_CANCEL_DEFERRED nor PTHREAD_CANCEL_ASYNCHRONOUS +

Author

Xavier Leroy <Xavier.Leroy@inria.fr> +

Modified by Ross Johnson for use with Pthreads-w32.

Bugs

+

pthread_setcanceltype(PTHREAD_CANCEL_ASYNCHRONOUS, &oldCancelType);
+read(fd, buffer, length);
+pthread_setcanceltype(oldCancelType, NULL);

Table of Contents

Name +
+
Synopsis +
+
Description +
+
Return + Value +
+
Errors +
+
Author +
+
See + Also +
+
Bugs +
+

+ + diff --git a/manual/pthread_setconcurrency.html b/manual/pthread_setconcurrency.html new file mode 100644 index 0000000..cdd4f58 --- /dev/null +++ b/manual/pthread_setconcurrency.html @@ -0,0 +1,155 @@ + + + + + "PTHREAD_GETCONCURRENCY"(P) manual page + + + + + + + +

POSIX Threads for Windows – REFERENCE - Pthreads-w32

Reference Index

Table of Contents

Name

pthread_getconcurrency, pthread_setconcurrency - get and set the +level of concurrency +

Synopsis

#include <pthread.h> +

int pthread_getconcurrency(void);
int +pthread_setconcurrency(int new_level); +

Description

Unbound threads in a process may or may not be required to be +simultaneously active. By default, the threads implementation ensures +that a sufficient number of threads are active so that the process +can continue to make progress. While this conserves system resources, +it may not produce the most effective level of concurrency. +

The pthread_setconcurrency function allows an application +to inform the threads implementation of its desired concurrency +level, new_level. The actual level of concurrency provided by +the implementation as a result of this function call is unspecified. +

If new_level is zero, it causes the implementation to +maintain the concurrency level at its discretion as if +pthread_setconcurrency had never been called. +

The pthread_getconcurrency function shall return the value +set by a previous call to the pthread_setconcurrency function. +If the pthread_setconcurrency function was not previously +called, this function shall return zero to indicate that the +implementation is maintaining the concurrency level. +

A call to pthread_setconcurrency shall inform the +implementation of its desired concurrency level. The implementation +shall use this as a hint, not a requirement. +

If an implementation does not support multiplexing of user threads +on top of several kernel-scheduled entities, the +pthread_setconcurrency and pthread_getconcurrency +functions are provided for source code compatibility but they shall +have no effect when called. To maintain the function semantics, the +new_level parameter is saved when pthread_setconcurrency +is called so that a subsequent call to pthread_getconcurrency +shall return the same value. +

Pthreads-w32 provides these routines for source code +compatibility only, as described in the previous paragraph.

Return Value

If successful, the pthread_setconcurrency function shall +return zero; otherwise, an error number shall be returned to indicate +the error. +

The pthread_getconcurrency function shall always return the +concurrency level set by a previous call to pthread_setconcurrency +. If the pthread_setconcurrency function has never been +called, pthread_getconcurrency shall return zero. +

Errors

The pthread_setconcurrency function shall fail if: +

EINVAL +: + The value specified by new_level is negative. +
+ EAGAIN +: + The value specific by new_level would cause a system resource + to be exceeded. +

+These functions shall not return an error code of [EINTR]. +

The following sections are informative. +

Examples

None. +

Application Usage

Use of these functions changes the state of the underlying +concurrency upon which the application depends. Library developers +are advised to not use the pthread_getconcurrency and +pthread_setconcurrency functions since their use may conflict +with an applications use of these functions. +

Rationale

None. +

Future Directions

None. +

Copyright

Modified by Ross Johnson for use with Pthreads-w32.

Table of Contents

Name +
+
Synopsis +
+
Description +
+
Return + Value +
+
Errors +
+
Examples +
+
Application + Usage +
+
Rationale +
+
Future + Directions +
+
See + Also +
+
Copyright +
+

+ + diff --git a/manual/pthread_setschedparam.html b/manual/pthread_setschedparam.html new file mode 100644 index 0000000..510ddf9 --- /dev/null +++ b/manual/pthread_setschedparam.html @@ -0,0 +1,115 @@ + + + + + PTHREAD_SETSCHEDPARAM(3) manual page + + + + + + + +

POSIX Threads for Windows – REFERENCE - Pthreads-w32

Reference Index

Table of Contents

Name

pthread_setschedparam, pthread_getschedparam - control thread +scheduling +

parameters +

Synopsis

#include <pthread.h> +

int pthread_setschedparam(pthread_t target_thread, +int policy, const struct sched_param *param); +

int pthread_getschedparam(pthread_t target_thread, +int *policy, struct sched_param *param); +

Description

pthread_setschedparam sets the scheduling parameters for +the thread target_thread as indicated by policy and +param. policy can be either SCHED_OTHER +(regular, non-real-time scheduling), SCHED_RR (real-time, +round-robin) or SCHED_FIFO (real-time, first-in first-out). +param specifies the scheduling priority for the two real-time +policies. See sched_setpolicy(2) +for more information on scheduling policies. +

Pthreads-w32 only supports SCHED_OTHER and does not support +the real-time scheduling policies SCHED_RR and SCHED_FIFO. +

pthread_getschedparam retrieves the scheduling policy and +scheduling parameters for the thread target_thread and stores +them in the locations pointed to by policy and param, +respectively. +

Return Value

pthread_setschedparam and pthread_getschedparam +return 0 on success and a non-zero error code on error. +

Errors

On error, pthread_setschedparam returns the following error +codes: +

ENOTSUP +: + policy is not SCHED_OTHER.
+ EINVAL +: + One of the arguments is invalid, or the priority value specified by + param is not valid for the specified policy.
+ ESRCH +: + The target_thread is invalid or has already terminated +

+ +

+On error, pthread_getschedparam returns the following error +codes: +

ESRCH +: + the target_thread is invalid or has already terminated +

+ +

+Author

Xavier Leroy <Xavier.Leroy@inria.fr> +

Modified by Ross Johnson for use with Pthreads-w32.

Name

pthread_spin_destroy, pthread_spin_init - destroy or initialize a +spin lock object (ADVANCED REALTIME THREADS) +

Synopsis

#include <pthread.h> +

pthread_spinlock_t lock = +PTHREAD_SPINLOCK_INITIALIZER;

int pthread_spin_destroy(pthread_spinlock_t *lock); +
int pthread_spin_init(pthread_spinlock_t *lock, int +pshared); +

Description

The pthread_spin_destroy function shall destroy the spin +lock referenced by lock and release any resources used by the +lock. The effect of subsequent use of the lock is undefined until the +lock is reinitialized by another call to pthread_spin_init . +The results are undefined if pthread_spin_destroy is called +when a thread holds the lock, or if this function is called with an +uninitialized thread spin lock. +

The pthread_spin_init function shall allocate any resources +required to use the spin lock referenced by lock and +initialize the lock to an unlocked state. +

Pthreads-w32 supports single and multiple processor systems +as well as process CPU affinity masking by checking the mask when the +spin lock is initialized. If the process is using only a single +processor at the time pthread_spin_init is called then the +spin lock is initialized as a PTHREAD_MUTEX_NORMAL mutex object. A +thread that calls pthread_spin_lock(3) +will block rather than spin in this case. If the process CPU affinity +mask is altered after the spin lock has been initialised, the spin +lock is not modified, and may no longer be optimal for the number of +CPUs available.

Pthreads-w32 defines _POSIX_THREAD_PROCESS_SHARED in +pthread.h as -1 to indicate that these routines do not support the +PTHREAD_PROCESS_SHARED attribute. pthread_spin_init +will return the error ENOTSUP if the value of pshared +is not PTHREAD_PROCESS_PRIVATE.

The results are undefined if pthread_spin_init is called +specifying an already initialized spin lock. The results are +undefined if a spin lock is used without first being initialized. +

If the pthread_spin_init function fails, the lock is not +initialized and the contents of lock are undefined. +

Only the object referenced by lock may be used for +performing synchronization. +

The result of referring to copies of that object in calls to +pthread_spin_destroy , pthread_spin_lock(3) +, pthread_spin_trylock(3), +or pthread_spin_unlock(3) +is undefined. +

Pthreads-w32 supports statically initialized spin locks +using PTHREAD_SPINLOCK_INITIALIZER. An application should +still call pthread_spin_destroy at some point to ensure that +any resources consumed by the spin lock are released.

Return Value

Upon successful completion, these functions shall return zero; +otherwise, an error number shall be returned to indicate the error. +

Errors

These functions may fail if: +

EBUSY +: + The implementation has detected an attempt to initialize or destroy + a spin lock while it is in use (for example, while being used in a + pthread_spin_lock(3) + call) by another thread. +
+ EINVAL +: + The value specified by lock is invalid. +

+The pthread_spin_init function shall fail if: +

ENOTSUP +: + The value of pshared is not PTHREAD_PROCESS_PRIVATE.
+ ENOMEM +: + Insufficient memory exists to initialize the lock. +

+These functions shall not return an error code of [EINTR]. +

The following sections are informative. +

Examples

None. +

Application Usage

The pthread_spin_destroy and pthread_spin_init +functions are part of the Spin Locks option and need not be provided +on all implementations. +

Rationale

None. +

Future Directions

None. +

Copyright

Modified by Ross Johnson for use with Pthreads-w32.

Table of Contents

Name +
+
Synopsis +
+
Description +
+
Return + Value +
+
Errors +
+
Examples +
+
Application + Usage +
+
Rationale +
+
Future + Directions +
+
See + Also +
+
Copyright +
+

+ + diff --git a/manual/pthread_spin_lock.html b/manual/pthread_spin_lock.html new file mode 100644 index 0000000..dd180ae --- /dev/null +++ b/manual/pthread_spin_lock.html @@ -0,0 +1,141 @@ + + + + + "PTHREAD_SPIN_LOCK"(P) manual page + + + + + + + +

POSIX Threads for Windows – REFERENCE - Pthreads-w32

Reference Index

Table of Contents

Name

pthread_spin_lock, pthread_spin_trylock - lock a spin lock object +(ADVANCED REALTIME THREADS) +

Synopsis

#include <pthread.h> +

int pthread_spin_lock(pthread_spinlock_t *lock); +
int pthread_spin_trylock(pthread_spinlock_t *lock); + +

Description

The pthread_spin_lock function shall lock the spin lock +referenced by lock. The calling thread shall acquire the lock +if it is not held by another thread. Otherwise, the thread shall spin +(that is, shall not return from the pthread_spin_lock call) +until the lock becomes available. The results are undefined if the +calling thread holds the lock at the time the call is made.

Pthreads-w32 supports single and multiple processor systems +as well as process CPU affinity masking by checking the mask when the +spin lock is initialized. If the process is using only a single +processor at the time pthread_spin_init(3) +is called then the spin lock is initialized as a PTHREAD_MUTEX_NORMAL +mutex object. A thread that calls pthread_spin_lock will block +rather than spin in this case. If the process CPU affinity mask is +altered after the spin lock has been initialised, the spin lock is +not modified, and may no longer be optimal for the number of CPUs +available.

The pthread_spin_trylock function shall lock the spin lock +referenced by lock if it is not held by any thread. Otherwise, +the function shall fail. +

The results are undefined if any of these functions is called with +an uninitialized spin lock. +

Return Value

Upon successful completion, these functions shall return zero; +otherwise, an error number shall be returned to indicate the error. +

Errors

These functions may fail if: +

EINVAL +: + The value specified by lock does not refer to an initialized + spin lock object. +

+The pthread_spin_trylock function shall fail if: +

EBUSY +: + A thread currently holds the lock. +

+These functions shall not return an error code of [EINTR]. +

The following sections are informative. +

Examples

None. +

Application Usage

Applications using this function may be subject to priority +inversion, as discussed in the Base Definitions volume of +IEEE Std 1003.1-2001, Section 3.285, Priority Inversion. +

Rationale

None. +

Future Directions

None. +

Copyright

Modified by Ross Johnson for use with Pthreads-w32.

Table of Contents

Name +
+
Synopsis +
+
Description +
+
Return + Value +
+
Errors +
+
Examples +
+
Application + Usage +
+
Rationale +
+
Future + Directions +
+
See + Also +
+
Copyright +
+

+ + diff --git a/manual/pthread_spin_unlock.html b/manual/pthread_spin_unlock.html new file mode 100644 index 0000000..2215700 --- /dev/null +++ b/manual/pthread_spin_unlock.html @@ -0,0 +1,124 @@ + + + + + "PTHREAD_SPIN_UNLOCK"(P) manual page + + + + + + + +

POSIX Threads for Windows – REFERENCE - Pthreads-w32

Reference Index

Table of Contents

Name

pthread_spin_unlock - unlock a spin lock object (ADVANCED +REALTIME THREADS) +

Synopsis

#include <pthread.h> +

int pthread_spin_unlock(pthread_spinlock_t *lock); + +

Description

The pthread_spin_unlock function shall release the spin +lock referenced by lock which was locked via the +pthread_spin_lock(3) or +pthread_spin_trylock(3) +functions. If there are threads spinning on the lock when +pthread_spin_unlock is called, the lock becomes available and +an unspecified spinning thread shall acquire the lock. +

Pthreads-w32 does not check ownership of the lock and it is +therefore possible for a thread other than the locker to unlock the +spin lock. This is not a feature that should be exploited.

The results are undefined if this function is called with an +uninitialized thread spin lock. +

Return Value

Upon successful completion, the pthread_spin_unlock +function shall return zero; otherwise, an error number shall be +returned to indicate the error. +

Errors

The pthread_spin_unlock function may fail if: +

EINVAL +: + An invalid argument was specified. +; +
+

+This function shall not return an error code of [EINTR]. +

The following sections are informative. +

Examples

None. +

Application Usage

Pthreads-w32 does not check ownership of the lock and it is +therefore possible for a thread other than the locker to unlock the +spin lock. This is not a feature that should be exploited.

Rationale

None. +

Future Directions

None. +

Copyright

Modified by Ross Johnson for use with Pthreads-w32.

Table of Contents

Name +
+
Synopsis +
+
Description +
+
Return + Value +
+
Errors +
+
Examples +
+
Application + Usage +
+
Rationale +
+
Future + Directions +
+
See + Also +
+
Copyright +
+

+ + diff --git a/manual/pthread_timechange_handler_np.html b/manual/pthread_timechange_handler_np.html new file mode 100644 index 0000000..54226da --- /dev/null +++ b/manual/pthread_timechange_handler_np.html @@ -0,0 +1,76 @@ + + + + + PTHREAD_TIMECHANGE_HANDLER_NP manual page + + + + + + + +

POSIX Threads for Windows – REFERENCE - Pthreads-w32

Reference Index

Table of Contents

Name

pthread_timechange_handler_np – +alert timed waiting condition variables to system time changes.

Synopsis

#include <pthread.h> +

void * pthread_timechange_handler_np(void * dummy);

Description

To improve tolerance against operator or time service initiated +system clock changes.

pthread_timechange_handler_np can be called by an +application when it receives a WM_TIMECHANGE message from the system. +At present it broadcasts all condition variables so that waiting +threads can wake up and re-evaluate their conditions and restart +their timed waits if required.

pthread_timechange_handler_np has the same return type and +argument type as a thread routine so that it may be called directly +through pthread_create(), i.e. as a separate thread. If run as a +thread, the return code must be retrieved through pthread_join().

Although the dummy parameter is required it is not used and +any value including NULL can be given.

Cancellation

None.

Return Value

pthread_timechange_handler_np returns 0 on success, or an +error code.

Errors

The pthread_timechange_handler_np function returns the +following error code on error: +

EAGAIN +

+ +

+To indicate that not all condition variables were signalled for some +reason.

Author

Ross Johnson for use with Pthreads-w32.

Table of Contents

Name +
+
Synopsis +
+
Description +
+
Cancellation +
+
Return + Value +
+
Errors +
+
Author +
+

+ + diff --git a/manual/pthread_win32_attach_detach_np.html b/manual/pthread_win32_attach_detach_np.html new file mode 100644 index 0000000..57f0339 --- /dev/null +++ b/manual/pthread_win32_attach_detach_np.html @@ -0,0 +1,74 @@ + + + + + PTHREAD_WIN32_ATTACH_DETACH_NP manual page + + + + + + + +

POSIX Threads for Windows – REFERENCE - Pthreads-w32

Reference Index

Table of Contents

Name

pthread_win32_process_attach_np, +pthread_win32_process_detach_np, pthread_win32_thread_attach_np, +pthread_win32_thread_detach_np – exposed versions of the +pthreads-w32 DLL dllMain() switch functionality for use when +statically linking the library.

Synopsis

#include <pthread.h> +

BOOL pthread_win32_process_attach_np (void);

BOOL pthread_win32_process_detach_np (void);

BOOL pthread_win32_thread_attach_np (void);

BOOL pthread_win32_thread_detach_np (void);

Description

These functions contain the code normally run via dllMain +when the library is used as a dll but which need to be called +explicitly by an application when the library is statically linked.

You will need to call pthread_win32_process_attach_np +before you can call any pthread routines when statically linking. You +should call pthread_win32_process_detach_np before exiting +your application to clean up.

pthread_win32_thread_attach_np is currently a no-op, but +pthread_win32_thread_detach_np is needed to clean up the +implicit pthread handle that is allocated to a Win32 thread if it +calls certain pthreads routines. Call this routine when the Win32 +thread exits.

These functions invariably return TRUE except for +pthread_win32_process_attach_np which will return FALSE if +pthreads-w32 initialisation fails.

Cancellation

None.

Return Value

These routines return TRUE (non-zero) on success, or FALSE (0) if +they fail.

Errors

None.

Author

Ross Johnson for use with Pthreads-w32.

Table of Contents

Name +
+
Synopsis +
+
Description +
+
Cancellation +
+
Return + Value +
+
Errors +
+
Author +
+

+ + diff --git a/manual/pthread_win32_test_features_np.html b/manual/pthread_win32_test_features_np.html new file mode 100644 index 0000000..908bb77 --- /dev/null +++ b/manual/pthread_win32_test_features_np.html @@ -0,0 +1,72 @@ + + + + + PTHREAD_WIN32_TEST_FEATURES_NP manual page + + + + + + + +

POSIX Threads for Windows – REFERENCE - Pthreads-w32

Reference Index

Table of Contents

Name

pthread_win32_test_features_np – +find out what features were detected at process attach time.

Synopsis

#include <pthread.h> +

BOOL pthread_win32_test_features_np(int mask);

Description

pthread_win32_test_features_np allows an application to +check which run-time auto-detected features are available within the +library.

The possible features are:

PTW32_SYSTEM_INTERLOCKED_COMPARE_EXCHANGE

Return TRUE if the Win32 version of +InterlockedCompareExchange() is being used. On IA32 systems the +library can use optimised and inlinable assembler versions of +InterlockedExchange() and InterlockedCompareExchange().

PTW32_ALERTABLE_ASYNC_CANCEL

Return TRUE if the QueueUserAPCEx package +QUSEREX.DLL and the AlertDrv.sys driver was detected. This package +provides alertable (pre-emptive) asynchronous threads cancellation. +If this feature returns FALSE then the default async cancel scheme +is in use, which cannot cancel blocked threads.

Features may be OR'ed into the mask parameter, in which case the +routine returns TRUE if any of the OR'ed features would +return TRUE. At this stage it doesn't make sense to OR features but +it may some day.

Cancellation

None.

Return Value

pthread_win32_test_features_np returns TRUE (non-zero) if +any of the specified features is present, and FALSE (0) otherwise.

Errors

None.

Author

Ross Johnson for use with Pthreads-w32.

Table of Contents

Name +
+
Synopsis +
+
Description +
+
Cancellation +
+
Return + Value +
+
Errors +
+
Author +
+

+ + diff --git a/manual/sched_get_priority_max.html b/manual/sched_get_priority_max.html new file mode 100644 index 0000000..30e00eb --- /dev/null +++ b/manual/sched_get_priority_max.html @@ -0,0 +1,118 @@ + + + + + "SCHED_GET_PRIORITY_MAX"(P) manual page + + + + + + + +

POSIX Threads for Windows – REFERENCE - Pthreads-w32

Reference Index

Table of Contents

Name

sched_get_priority_max, sched_get_priority_min - get priority +limits (REALTIME) +

Synopsis

#include <sched.h> +

int sched_get_priority_max(int policy);
int +sched_get_priority_min(int policy); +

Description

The sched_get_priority_max and sched_get_priority_min +functions shall return the appropriate maximum or minimum, +respectively, for the scheduling policy specified by policy. +

The value of policy shall be one of the scheduling policy +values defined in <sched.h>. +

Return Value

If successful, the sched_get_priority_max and +sched_get_priority_min functions shall return the appropriate +maximum or minimum values, respectively. If unsuccessful, they shall +return a value of -1 and set errno to indicate the error. +

Errors

The sched_get_priority_max and sched_get_priority_min +functions shall fail if: +

EINVAL +: + The value of the policy parameter does not represent a + defined scheduling policy. +

+The following sections are informative. +

Examples

None. +

Application Usage

None. +

Rationale

None. +

Future Directions

None. +

Copyright

Modified by Ross Johnson for use with Pthreads-w32.

Table of Contents

Name +
+
Synopsis +
+
Description +
+
Return + Value +
+
Errors +
+
Examples +
+
Application + Usage +
+
Rationale +
+
Future + Directions +
+
See + Also +
+
Copyright +
+

+ + diff --git a/manual/sched_getscheduler.html b/manual/sched_getscheduler.html new file mode 100644 index 0000000..0089e24 --- /dev/null +++ b/manual/sched_getscheduler.html @@ -0,0 +1,127 @@ + + + + + "SCHED_GETSCHEDULER"(P) manual page + + + + + + + +

POSIX Threads for Windows – REFERENCE - Pthreads-w32

Reference Index

Table of Contents

Name

sched_getscheduler - get scheduling policy (REALTIME) +

Synopsis

#include <sched.h> +

int sched_getscheduler(pid_t pid); +

Description

The sched_getscheduler function shall return the scheduling +policy of the process specified by pid. If the value of pid +is negative, the behavior of the sched_getscheduler function +is unspecified. +

The values that can be returned by sched_getscheduler are +defined in the <sched.h> header. +

Pthreads-w32 only supports the SCHED_OTHER policy, +which is the only value that can be returned. However, checks on pid +and permissions are performed first so that the other useful side +effects of this routine are retained.

If a process specified by pid exists, and if the calling +process has permission, the scheduling policy shall be returned for +the process whose process ID is equal to pid. +

If pid is zero, the scheduling policy shall be returned for +the calling process. +

Return Value

Upon successful completion, the sched_getscheduler function +shall return the scheduling policy of the specified process. If +unsuccessful, the function shall return -1 and set errno to +indicate the error. +

Errors

The sched_getscheduler function shall fail if: +

EPERM +: + The requesting process does not have permission to determine the + scheduling policy of the specified process. +
+ ESRCH +: + No process can be found corresponding to that specified by pid. +

+The following sections are informative. +

Examples

None. +

Application Usage

None. +

Rationale

None. +

Future Directions

None. +

Copyright

Modified by Ross Johnson for use with Pthreads-w32.

Table of Contents

Name +
+
Synopsis +
+
Description +
+
Return + Value +
+
Errors +
+
Examples +
+
Application + Usage +
+
Rationale +
+
Future + Directions +
+
See + Also +
+
Copyright +
+

+ + diff --git a/manual/sched_setscheduler.html b/manual/sched_setscheduler.html new file mode 100644 index 0000000..c6e62ae --- /dev/null +++ b/manual/sched_setscheduler.html @@ -0,0 +1,181 @@ + + + + + "SCHED_SETSCHEDULER"(P) manual page + + + + + + + +

POSIX Threads for Windows – REFERENCE - Pthreads-w32

Reference Index

Table of Contents

Name

sched_setscheduler - set scheduling policy and parameters +(REALTIME) +

Synopsis

#include <sched.h> +

int sched_setscheduler(pid_t pid, int policy, +const struct sched_param *param); +

Description

The sched_setscheduler function shall set the scheduling +policy and scheduling parameters of the process specified by pid +to policy and the parameters specified in the sched_param +structure pointed to by param, respectively. The value of the +sched_priority member in the sched_param structure +shall be any integer within the inclusive priority range for the +scheduling policy specified by policy. If the value of pid +is negative, the behavior of the sched_setscheduler function +is unspecified. +

The possible values for the policy parameter are defined in +the <sched.h> header. +

Pthreads-w32 only supports the SCHED_OTHER policy. +Any other value for policy will return failure with errno set +to ENOSYS. However, checks on pid and permissions are +performed first so that the other useful side effects of this routine +are retained.

If a process specified by pid exists, and if the calling +process has permission, the scheduling policy and scheduling +parameters shall be set for the process whose process ID is equal to +pid. +

If pid is zero, the scheduling policy and scheduling +parameters shall be set for the calling process. +

Implementations may require that the requesting process have +permission to set its own scheduling parameters or those of another +process. Additionally, implementation-defined restrictions may apply +as to the appropriate privileges required to set a process’ own +scheduling policy, or another process’ scheduling policy, to a +particular value. +

The sched_setscheduler function shall be considered +successful if it succeeds in setting the scheduling policy and +scheduling parameters of the process specified by pid to the +values specified by policy and the structure pointed to by +param, respectively. +

The effect of this function on individual threads is dependent on +the scheduling contention scope of the threads: +

* +: + For threads with system scheduling contention scope, these functions + shall have no effect on their scheduling. +
+ * +: + For threads with process scheduling contention scope, the threads’ + scheduling policy and associated parameters shall not be affected. + However, the scheduling of these threads with respect to threads in + other processes may be dependent on the scheduling parameters of + their process, which are governed using these functions. +

+This function is not atomic with respect to other threads in the +process. Threads may continue to execute while this function call is +in the process of changing the scheduling policy and associated +scheduling parameters for the underlying kernel-scheduled entities +used by the process contention scope threads. +

Return Value

Upon successful completion, the function shall return the former +scheduling policy of the specified process. If the sched_setscheduler +function fails to complete successfully, the policy and scheduling +parameters shall remain unchanged, and the function shall return a +value of -1 and set errno to indicate the error. +

Errors

The sched_setscheduler function shall fail if: +

EINVAL +: + The value of the policy parameter is invalid, or one or more + of the parameters contained in param is outside the valid + range for the specified scheduling policy. +
+ EPERM +: + The requesting process does not have permission to set either or + both of the scheduling parameters or the scheduling policy of the + specified process. +
+ ESRCH +: + No process can be found corresponding to that specified by pid. +

+The following sections are informative. +

Examples

None. +

Application Usage

None. +

Rationale

None. +

Future Directions

None. +

Copyright

Modified by Ross Johnson for use with Pthreads-w32.

Table of Contents

Name +
+
Synopsis +
+
Description +
+
Return + Value +
+
Errors +
+
Examples +
+
Application + Usage +
+
Rationale +
+
Future + Directions +
+
See + Also +
+
Copyright +
+

+ + diff --git a/manual/sched_yield.html b/manual/sched_yield.html new file mode 100644 index 0000000..fa5ed04 --- /dev/null +++ b/manual/sched_yield.html @@ -0,0 +1,98 @@ + + + + + "SCHED_YIELD"(P) manual page + + + + + + + +

POSIX Threads for Windows – REFERENCE - Pthreads-w32

Reference Index

Table of Contents

Name

sched_yield - yield the processor +

Synopsis

#include <sched.h> +

int sched_yield(void); +

Description

The sched_yield function shall force the running thread to +relinquish the processor until it again becomes the head of its +thread list. It takes no arguments. +

Return Value

The sched_yield function shall return 0 if it completes +successfully; otherwise, it shall return a value of -1 and set errno +to indicate the error. +

Errors

No errors are defined. +

The following sections are informative. +

Examples

None. +

Application Usage

None. +

Rationale

None. +

Future Directions

None. +

Copyright

Table of Contents

Name +
+
Synopsis +
+
Description +
+
Return + Value +
+
Errors +
+
Examples +
+
Application + Usage +
+
Rationale +
+
Future + Directions +
+
See + Also +
+
Copyright +
+

+ + diff --git a/manual/sem_init.html b/manual/sem_init.html new file mode 100644 index 0000000..5509859 --- /dev/null +++ b/manual/sem_init.html @@ -0,0 +1,202 @@ + + + + + SEMAPHORES(3) manual page + + + + + + + +

POSIX Threads for Windows – REFERENCE - Pthreads-w32

Reference Index

Table of Contents

Name

sem_init, sem_wait, sem_trywait, sem_post, sem_getvalue, +sem_destroy - operations on semaphores +

Synopsis

#include <semaphore.h> +

int sem_init(sem_t *sem, int pshared, +unsigned int value); +

int sem_wait(sem_t * sem); +

int sem_timedwait(sem_t * sem, +const struct timespec *abstime); +

int sem_trywait(sem_t * sem); +

int sem_post(sem_t * sem); +

int sem_post_multiple(sem_t * sem, int +number); +

int sem_getvalue(sem_t * sem, int * sval); +

int sem_destroy(sem_t * sem); +

Description

Semaphores are counters for resources shared between threads. The +basic operations on semaphores are: increment the counter atomically, +and wait until the counter is non-null and decrement it atomically. +

sem_init initializes the semaphore object pointed to by +sem. The count associated with the semaphore is set initially +to value. The pshared argument indicates whether the +semaphore is local to the current process ( pshared is zero) +or is to be shared between several processes ( pshared is not +zero).

Pthreads-w32 currently does not support process-shared +semaphores, thus sem_init always returns with error EPERM +if pshared is not zero. +

sem_wait atomically decrements sem's count if it is +greater than 0 and returns immediately or it suspends the calling +thread until it can resume following a call to sem_post +or sem_post_multiple.

sem_timedwait atomically decrements sem's count if +it is greater than 0 and returns immediately, or it suspends the +calling thread. If abstime time arrives before the thread can +resume following a call to sem_post or sem_post_multiple, +then sem_timedwait returns with a return code of -1 after +having set errno to ETIMEDOUT. If the call can return +without suspending then abstime is not checked.

sem_trywait atomically +decrements sem's count if it is greater than 0 and returns +immediately, or it returns immediately with a return code of -1 after +having set errno to EAGAIN. sem_trywait +never blocks.

sem_post either releases one thread if there are any +waiting on sem, or it atomically increments sem's +count.

sem_post_multiple either releases multiple threads if there +are any waiting on sem and/or +it atomically increases sem's count. If there are +currently n waiters, where n the largest number less +than or equal to number, then n waiters are released +and sem's count is incremented by number minus n.

sem_getvalue stores in the location pointed to by sval +the current count of the semaphore sem. In the Pthreads-w32 +implementation: if the value returned in sval is greater than +or equal to 0 it was the sem's count at some point during the +call to sem_getvalue. If the +value returned in sval is less than 0 then it's absolute value +represents the number of threads waiting on sem at some point +during the call to sem_getvalue. POSIX +does not require an implementation of sem_getvalue +to return a value in sval that is less than 0, but if it does +then it's absolute value must represent the number of waiters.

sem_destroy destroys a semaphore object, freeing the +resources it might hold. No threads should be waiting on the +semaphore at the time sem_destroy is called.

EINVAL +: + value exceeds the maximal counter value _POSIX_SEM_VALUE_MAX +
+ ENOSYS +

+ +

+pshared is not zero +

The sem_timedwait function sets errno to the +following error code on error: +

ETIMEDOUT +

+ +

+if abstime arrives before the waiting thread can resume +following a call to sem_post or sem_post_multiple. +

The sem_trywait function sets errno to the following +error code on error: +

EAGAIN +

+ +

+if the semaphore count is currently 0 +

The sem_post and sem_post_multiple functions set +errno to the following error code on error: +

ERANGE +: + if after incrementing, the semaphore count would exceed + _POSIX_SEM_VALUE_MAX (the semaphore count is left unchanged + in this case) +

+ +

+The sem_destroy function sets errno to the following +error code on error: +

EBUSY +: + if some threads are currently blocked waiting on the semaphore. +

+ +

+Author

Xavier Leroy <Xavier.Leroy@inria.fr> +

Modified by Ross Johnson for use with Pthreads-w32.