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

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

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
>

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