From 4f623056c916678dd77844e22e4c9012c7ff09f7 Mon Sep 17 00:00:00 2001 From: rpj Date: Sat, 26 Mar 2011 04:18:48 +0000 Subject: Add new sections --- manual/ChangeLog | 10 +- manual/index.html | 277 +++++++++++++++++++------------------ manual/pthread_mutex_init.html | 225 ++++++++++++++++++++---------- manual/pthread_mutexattr_init.html | 172 +++++++++++++++-------- 4 files changed, 416 insertions(+), 268 deletions(-) (limited to 'manual') diff --git a/manual/ChangeLog b/manual/ChangeLog index ae3c308..071b847 100644 --- a/manual/ChangeLog +++ b/manual/ChangeLog @@ -1,6 +1,14 @@ +2011-03-26 Ross Johnson + + * pthread_nutex_init.html (robust mutexes): Added + descriptions for newly implemented interface. + * pthread_mutexattr_init.html (robust mutexes): Likewise. + * pthread_getsequence_np.html: New. + * index.html: Updated. + 2008-06-30 Ross Johnson - pthread_setschedparam.html: Fix "see also" links. + * pthread_setschedparam.html: Fix "see also" links. 2005-05-06 Ross Johnson diff --git a/manual/index.html b/manual/index.html index a209dc0..f11f2d6 100644 --- a/manual/index.html +++ b/manual/index.html @@ -3,144 +3,155 @@ - + - + + + -

POSIX Threads for Windows – REFERENCE - Pthreads-w32

sem_close

sem_destroy

sem_getvalue

sem_init

sem_open

sem_post

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 +

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_create
+
pthread_detach
+
pthread_equal
+
pthread_exit
+
pthread_getconcurrency
+
pthread_getschedparam
+
pthread_getsequence_np
+
pthread_getspecific
+
pthread_join
+
pthread_key_create
+
pthread_key_delete
+
pthread_kill
+
pthread_mutexattr_destroy
+
pthread_mutexattr_getkind_np
+
pthread_mutexattr_getpshared
+
pthread_mutexattr_getrobust
+
pthread_mutexattr_gettype
+
pthread_mutexattr_init
+
pthread_mutexattr_setkind_np
+
pthread_mutexattr_setpshared
+
pthread_mutexattr_setrobust
+
pthread_mutexattr_settype
+
pthread_mutex_consistent
+
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
+
sched_yield
+
sem_close
+
sem_destroy
+
sem_getvalue
+
sem_init
+
sem_open
+
sem_post
+
sem_post_multiple
+
sem_timedwait
+
sem_trywait
+
sem_unlink
+
sem_wait
+
sigwait
+
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
- + \ No newline at end of file diff --git a/manual/pthread_mutex_init.html b/manual/pthread_mutex_init.html index f9982cf..cdb333e 100644 --- a/manual/pthread_mutex_init.html +++ b/manual/pthread_mutex_init.html @@ -3,22 +3,37 @@ PTHREAD_MUTEX(3) manual page - + - + + + + + -
POSIX Threads for Windows – REFERENCE - Pthreads-w32
+
POSIX Threads for Windows – REFERENCE - +Pthreads-w32

Reference Index

Table of Contents
-
Name
+
Name

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

#include <pthread.h>

#include <time.h>
@@ -49,9 +64,11 @@ const pthread_mutexattr_t *mutexattr);

int pthread_mutex_unlock(pthread_mutex_t *mutex);

int pthread_mutex_consistent(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. @@ -76,16 +93,22 @@ for more information on mutex attributes. 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 +(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.

Any mutex type can be +initialized as a robust mutex. +See pthread_mutexattr_init(3) +for more information as well as the +section Robust Mutexes +below.

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. -

+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 @@ -101,15 +124,18 @@ 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. +calling thread in the case of a “normal” or “errorcheck” +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_consistent may only be called for +PTHREAD_MUTEX_ROBUST mutexes. It simply marks the mutex as +consistent. See Robust Mutexes below.

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” @@ -117,19 +143,53 @@ 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. -

+count reaches zero is the mutex actually unlocked. In Pthreads-win32, +non-robust normal or default mutex types do not check the owner of +the mutex. For all types of robust mutexes the owner is checked and +an error code is returned if the calling thread does not own the +mutex.

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.

+[non-robust] 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

Robust Mutexes

If the mutex is PTHREAD_MUTEX_ROBUST and the owning thread +terminates without unlocking the mutex the implementation will wake +one waiting thread, if any. The next thread to acquire the mutex will +receive the error code EOWNERDEAD, +in which case that thread should if possible ensure that the state +protected by the mutex is consistent and then call +pthread_mutex_consistent before +unlocking. The mutex may then be used normally from then on.

If the thread cannot recover the +state then it must call pthread_mutex_unlock +without calling pthread_mutex_consistent. +This will mark the mutex as unusable and wake all currently waiting +threads with the return code ENOTRECOVERABLE. +The error indicates that the mutex is no longer usable and any +threads that receive this error code from any lock operation have not +acquired the mutex. The mutex can be made consistent by calling +pthread_mutex_destroy to +uninitialize the mutex, and calling pthread_mutex_int +to reinitialize the mutex. However, +the state that was protected by the mutex remains inconsistent and +some form of application recovery is required.

If a thread that receives the +EOWNERDEAD error code +itself terminates without unlocking the mutex then this behaviour +repeats for the next acquiring thread.

Applications must ensure that +they check the return values from all calls targeting robust mutexes.

Robust mutexes are slower because they +require some additional overhead, however they are not very much +slower than the non-robust recursive type.

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 @@ -138,46 +198,56 @@ 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 -: +
EINVAL: the mutex has not been properly initialized. -
- EDEADLK -: +
+ 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: -

+ The pthread_mutex_trylock function returns the following + error codes on error: +
+ EOWNERDEAD: + the robust mutex is now locked by the calling thread after the + previous owner terminated without unlocking it.
+ ENOTRECOVERABLE: + the robust mutex is not locked and is no longer usable after the + previous owner unlocked it without calling + pthread_mutex_consistent.

The pthread_mutex_timedlock function returns the following @@ -185,15 +255,22 @@ error codes on error:

+ EOWNERDEAD: + the robust mutex is now locked by the calling thread after the + previous owner terminated without unlocking it.
+ ENOTRECOVERABLE: + the robust mutex is not locked and is no longer usable after the + previous owner unlocked it without calling + pthread_mutex_consistent.

The pthread_mutex_unlock function returns the following error @@ -201,12 +278,12 @@ code on error:

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

@@ -217,61 +294,63 @@ code on error:

EBUSY -: +
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;

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);
+pthread_mutex_lock(&mut);
 /* operate on x */
 pthread_mutex_unlock(&mut);
 
-Table of
-Contents
+Table
+of Contents
 
-	Name
+	Name
 		
-	
Synopsis
+	Synopsis
 		
-	
Description
+	Description
 		
-	
Cancellation
+	Robust
+	Mutexes
+	
Cancellation
 		
-	
Async-signal
+	Async-signal
 	Safety 
 	
-	
Return
+	Return
 	Value 
 	
-	
Errors
+	Errors
 		
-	
Author
+	Author
 		
-	
See
+	See
 	Also 
 	
-	
Example
+	Example
 		
 
 
-
+
\ No newline at end of file
diff --git a/manual/pthread_mutexattr_init.html b/manual/pthread_mutexattr_init.html
index f3df993..f69599b 100644
--- a/manual/pthread_mutexattr_init.html
+++ b/manual/pthread_mutexattr_init.html
@@ -3,22 +3,32 @@
 
 	
 	PTHREAD_MUTEXATTR(3) manual page
-	
+	
 	
-	
+	
+	
 	
 	
+	
 
 
-POSIX Threads for Windows – REFERENCE - Pthreads-w32
+POSIX Threads for Windows – REFERENCE -
+Pthreads-w32
 Reference Index
 Table of Contents
-Name
+Name
 pthread_mutexattr_init, pthread_mutexattr_destroy,
 pthread_mutexattr_settype, pthread_mutexattr_gettype - mutex creation
 attributes 
 
-Synopsis
+Synopsis
 #include <pthread.h> 
 
 int pthread_mutexattr_init(pthread_mutexattr_t *attr);
@@ -37,7 +47,13 @@ int type);
 
int pthread_mutexattr_getkind_np(const pthread_mutexattr_t
 *attr, int *type); 
 
-Description
+int pthread_mutexattr_setrobust(pthread_mutexattr_t *attr,
+int robust);
+
+int pthread_mutexattr_getrobust(pthread_mutexattr_t *attr,
+int *robust);
+
+Description
 Mutex attributes can be specified at mutex creation time, by
 passing a mutex attribute object as second argument to
 pthread_mutex_init(3) .
@@ -50,12 +66,27 @@ attributes.
 
 pthread_mutexattr_destroy destroys a mutex attribute
 object, which must not be reused until it is reinitialized.
+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. 
+
 The following mutex types are supported:
-PTHREAD_MUTEX_NORMAL - for
+
PTHREAD_MUTEX_NORMAL - for
 ‘‘fast’’ mutexes.
-PTHREAD_MUTEX_RECURSIVE - for
+
PTHREAD_MUTEX_RECURSIVE - for
 ‘‘recursive’’ mutexes.
-PTHREAD_MUTEX_ERRORCHECK - for
+
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)
@@ -75,83 +106,102 @@ 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
+
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: 
-
+PTHREAD_MUTEX_RECURSIVE_NP
+PTHREAD_MUTEX_ERRORCHECK_NP
+pthread_mutexattr_setrobust
+sets the robustness attribute to the value given by robust.
+pthread_mutexattr_getrobust
+returns the current robustness value to the location given by
+*robust.
+The possible values for robust
+are:
+PTHREAD_MUTEX_STALLED
+- when the owner of the mutex terminates without unlocking the mutex,
+all subsequent calls
 to pthread_mutex_*lock() are blocked from
+progress in an unspecified manner.
+PTHREAD_MUTEX_ROBUST
+- when the owner of the mutex terminates without unlocking the mutex,
+the mutex is
 unlocked. The next owner of this mutex acquires the
+mutex with an error return of
EOWNERDEAD.
+Return Value
+On success all functions return
+0, otherwise they return an error code as follows:
+pthread_mutexattr_init
+ENOMEM
+- insufficient memory for attr.
+pthread_mutexattr_destroy
+EINVAL
+- attr
+is invalid.
+pthread_mutexattr_gettype
+EINVAL
+- attr
+is invalid.
+pthread_mutexattr_settype
 
-	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 
+	
+		
+			EINVAL - attr
+			is invalid or 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
+
+pthread_mutexattr_getrobust
+EINVAL
+– attr
+or robust
+is invalid.
+pthread_mutexattr_setrobust
+EINVAL
+– attr
+or robust
+is invalid.
+Author
 Xavier Leroy <Xavier.Leroy@inria.fr> 
 
 Modified by Ross Johnson for use with Pthreads-w32.
-See Also
+See Also
 pthread_mutex_init(3)
 , pthread_mutex_lock(3)
 , pthread_mutex_unlock(3)
 . 
 
-Notes
+Notes
 For speed, Pthreads-w32 never checks the thread ownership
-of mutexes of type PTHREAD_MUTEX_NORMAL (or
+of non-robust 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.
+When developing code, it is a common
+precaution to substitute the error checking type, then drop in the
+normal type for release if the extra performance is required.
 
 Table of Contents
 
-	Name
+	
Name
 		
-	
Synopsis
+	
Synopsis
 		
-	
Description
+	
Description
 		
-	
Return
+	
Return
 	Value 
 	
-	
Errors
-		
-	
Author
+	
Author
 		
-	
See
+	
See
 	Also
 	
Notes
 
 
-
+
\ No newline at end of file
-- 
cgit v1.2.3