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

[kemi <kemi dot wang at intel dot com>]

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