[RESEND,3/3] Manual: Add manual for pthread mutex

Message ID 1545049854-14472-3-git-send-email-kemi.wang@intel.com
State Superseded
Headers show
  • [RESEND,1/3] Mutex: Accelerate lock acquisition by queuing spinner
Related show

Commit Message

kemi Dec. 17, 2018, 12:30 p.m.
Pthread mutex is not described in the documentation, so I started to document
pthread mutex with PTHREAD_MUTEX_QUEUESPINNER type here at least.

Signed-off-by: Kemi Wang <kemi.wang@intel.com>

 manual/Makefile   |  2 +-
 manual/mutex.texi | 68 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 69 insertions(+), 1 deletion(-)
 create mode 100644 manual/mutex.texi



diff --git a/manual/Makefile b/manual/Makefile
index 5f6006d..0a8b80d 100644
--- a/manual/Makefile
+++ b/manual/Makefile
@@ -39,7 +39,7 @@  chapters = $(addsuffix .texi, \
 		       pipe socket terminal syslog math arith time	\
 		       resource setjmp signal startup process ipc job	\
 		       nss users sysinfo conf crypt debug threads	\
-		       probes tunables)
+		       probes tunables mutex)
 appendices = lang.texi header.texi install.texi maint.texi platform.texi \
 licenses = freemanuals.texi lgpl-2.1.texi fdl-1.3.texi
diff --git a/manual/mutex.texi b/manual/mutex.texi
new file mode 100644
index 0000000..1520a8c
--- /dev/null
+++ b/manual/mutex.texi
@@ -0,0 +1,68 @@ 
+@node Pthread mutex
+@c %MENU% mutex
+This chapter describes the usage and implmentation of POSIX Pthreads Mutex.
+* Mutex introduction:: What is mutex?
+* Mutex type:: The capability for each type of mutex
+* Mutex usage:: How to use mutex?
+* Usage scenarios and limitation::
+@end menu
+@node Mutex introduction
+@section Mutex introduction
+Mutex is used to protect the data structure shared among threads/processes.
+@node Mutex type
+@section Mutex type
+Queue spinner mutex can reduce the overhead of lock holder transition and
+make mutex scalable in a large system with more and more CPUs (E.g. NUMA
+architecture) by queuing spinners. It puts mutex spinners into a queue
+before spinning on the mutex lock and only allows one spinner spinning on
+mutex lock. Thus, when lock is released, the current spinner can acquire
+the lock immediately because the cache line including mutex lock is only
+contended between previous lock holder and current spinner, and the
+overhead of lock acquisition via spinning is always O(1) no matter how
+severe the lock is contended.
+@end deftp
+@node Mutex usage
+@section Mutex usage
+Queue spinner mutex can be initialized simply by either using the macro
+definition @code{PTHREAD_QUEUESPINNER_MUTEX_INITIALIZER_NP} or dynamically
+calling @code{pthread_mutex_init}.
+Static initialization:
+@end smallexample
+Dynamic initialization:
+pthread_mutexattr_settype(&attr, PTHREAD_MUTEX_QUEUESPINNER_NP)
+pthread_mutex_init(&mutex, &attr)
+@end smallexample
+@end deftp
+@node Usage scenarios and limitation
+@section Usage scenarios and limitation
+There could be a potential risk to use mutex initialized with type
+@code{PTHREAD_MUTEX_QUEUESPINNER_NP} if CPU resource is oversubscribed. E.g.
+when a lock holder is transferred to the next spinner in the queue. but it
+is not running (the CPU is scheduled to run other task at that moment).
+Thus, the other spinners have to wait and it may lead to lock performance
+collapse. Therefore, queue spinner mutex would be carefully used for
+applications to pursue performance and fairness without oversubsribing CPU
+resource. E.g. Run a application within a container in private or public
+cloud infrastructure or a application running on the CPUs without subscribed
+by other tasks at the same time.
+@end deftp