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

Message ID 1545286557-20901-3-git-send-email-kemi.wang@intel.com
State New
Headers show
Series
  • [v2,1/3] Mutex: Accelerate lock acquisition by queuing spinner
Related show

Commit Message

kemi Dec. 20, 2018, 6:15 a.m.
Pthread mutex is not described in the documentation, so I started to document
pthread mutex with PTHREAD_MUTEX_QUEUESPINNER_NP 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

-- 
2.7.4

Comments

Siddhesh Poyarekar Dec. 31, 2018, 5:49 p.m. | #1
On 20/12/18 11:45 AM, Kemi Wang wrote:
> Pthread mutex is not described in the documentation, so I started to document

> pthread mutex with PTHREAD_MUTEX_QUEUESPINNER_NP type here at least.

> 

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


Please add a ChangeLog entry.

> ---

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

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


There is already a file called threads.texi that has pthread function 
descriptions.  Please add your content there instead of creating a new 
file.  A high level comment here is that it needs  fair amount of 
additional detail to make it manual-worthy.  You could take a look at 
the C11 threads section in threads.texi to form similar content for 
pthread mutexes.

> @@ -0,0 +1,68 @@

> +@node Pthread mutex

> +@c %MENU% mutex

> +

> +This chapter describes the usage and implmentation of POSIX Pthreads Mutex.

> +

> +@menu

> +* 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

> +

> +@deftp Type PTHREAD_MUTEX_QUEUESPINNER_NP

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

> +

> +@deftp Type PTHREAD_MUTEX_QUEUESPINNER_NP

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

> +@smallexample

> +mutex = PTHREAD_QUEUESPINNER_MUTEX_INITIALIZER_NP

> +@end smallexample

> +

> +Dynamic initialization:

> +@smallexample

> +pthread_mutexattr_init(&attr)

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

> +

> +@deftp TYPE PTHREAD_MUTEX_QUEUESPINNER_NP

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

>
kemi Jan. 2, 2019, 1:45 a.m. | #2
On 2019/1/1 上午1:49, Siddhesh Poyarekar wrote:
> On 20/12/18 11:45 AM, Kemi Wang wrote:

>> Pthread mutex is not described in the documentation, so I started to document

>> pthread mutex with PTHREAD_MUTEX_QUEUESPINNER_NP type here at least.

>>

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

> 

> Please add a ChangeLog entry.

> 


OK

>> ---

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

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

> 

> There is already a file called threads.texi that has pthread function descriptions.  Please add your content there instead of creating a new file.  A high level comment here is that it needs  fair amount of additional detail to make it manual-worthy.  You could take a look at the C11 threads section in threads.texi to form similar content for pthread mutexes.

> 


OK. Thanks for your suggestion.

>> @@ -0,0 +1,68 @@

>> +@node Pthread mutex

>> +@c %MENU% mutex

>> +

>> +This chapter describes the usage and implmentation of POSIX Pthreads Mutex.

>> +

>> +@menu

>> +* 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

>> +

>> +@deftp Type PTHREAD_MUTEX_QUEUESPINNER_NP

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

>> +

>> +@deftp Type PTHREAD_MUTEX_QUEUESPINNER_NP

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

>> +@smallexample

>> +mutex = PTHREAD_QUEUESPINNER_MUTEX_INITIALIZER_NP

>> +@end smallexample

>> +

>> +Dynamic initialization:

>> +@smallexample

>> +pthread_mutexattr_init(&attr)

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

>> +

>> +@deftp TYPE PTHREAD_MUTEX_QUEUESPINNER_NP

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

>>

>

Patch

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 \
 	     contrib.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.
+
+@menu
+* 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
+
+@deftp Type PTHREAD_MUTEX_QUEUESPINNER_NP
+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
+
+@deftp Type PTHREAD_MUTEX_QUEUESPINNER_NP
+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:
+@smallexample
+mutex = PTHREAD_QUEUESPINNER_MUTEX_INITIALIZER_NP
+@end smallexample
+
+Dynamic initialization:
+@smallexample
+pthread_mutexattr_init(&attr)
+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
+
+@deftp TYPE PTHREAD_MUTEX_QUEUESPINNER_NP
+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