Re: [PATCH 08/14] Add manual for lock elision

["Carlos O'Donell" <carlos at redhat dot com>]

On 06/28/2013 10:50 AM, Andi Kleen wrote:
> On Fri, Jun 28, 2013 at 04:09:25AM -0400, Carlos O'Donell wrote:
>> On 06/28/2013 01:51 AM, Andi Kleen wrote:
>>> From: Andi Kleen <ak@linux.intel.com>
>>>
>>> pthreads are not described in the documentation, but I decided to document
>>> lock elision there at least.
>>
>> Can we please split this into two manual patches?
> 
> No, the constants conflicts with the environment patches are already a
> nightmare.  If that's a requirement I'll rather remove most of the manual.

I don't mind doing the work here.

If you want I can checkin a minimal documentation patch.

The changes I would propose look like the following incremental diff.

Cheers,
Carlos.

Patch #8 v2
- Fix spelling for completely and implicitly.
- Remove mention of new interfaces.
- Add some "Sorry not available yet" text.

diff --git a/manual/elision.texi b/manual/elision.texi
index 395819b..3ad1c32 100644
--- a/manual/elision.texi
+++ b/manual/elision.texi
@@ -32,11 +32,11 @@ can be transparently elided by @theglibc{}.
 Lock elision may lower performance if transaction aborts occur too frequently.
 In this case it is recommended to use a PMU profiler to find the causes for
 the aborts first and try to eliminate them. If that is not possible
-elision can be disabled for a specific lock or for the whole program.
-Alternatively elision can be disabled completly, and only enabled for 
-specific locks that are known to be elision friendly.
+elision can be disabled by using a version of the library compiled with
+elision turned off. Future support will include the ability to disable
+elision on a per-lock basis.
 
-The defaults locks are adaptive. The lock library decides whether elision
+The defaults locks are adaptive. The library decides whether elision
 is profitable based on the abort rates, and automatically disables
 elision for a lock when it aborts too often. After some time elision
 is re-tried, in case the workload changed.
@@ -82,7 +82,7 @@ early or could happen later, but will likely not happen every time.
 
 This behaviour is allowed in POSIX for @code{PTHREAD_MUTEX_DEFAULT}, but not for
 @code{PTHREAD_MUTEX_NORMAL}. When @code{PTHREAD_MUTEX_NORMAL} is
-set for a mutex using @code{pthread_mutexattr_settype} elision is implicitely
+set for a mutex using @code{pthread_mutexattr_settype} elision is implicitly
 disabled.  Note that @code{PTHREAD_MUTEX_INITIALIZER} sets a
 @code{PTHREAD_MUTEX_DEFAULT} type, thus allows elision.
 
@@ -169,40 +169,11 @@ nested in another elided lock.
 @node Setting elision for individual @code{pthread_mutex_t}
 @section Setting elision for individual @code{pthread_mutex_t}
 
-Elision can be explicitly disabled or enabled for each @code{pthread_mutex_t} in the program. 
-The elision flags can only be set at runtime using @code{pthread_mutexattr_setelision_np} and
-@code{pthread_mutex_init}. There is no support for initializers for them.
-
-@smallexample
-/* Force lock elision for a mutex */
-pthread_mutexattr_t attr;
-pthread_mutexattr_init (&attr);
-pthread_mutexattr_setelision_np (&attr, 1);
-pthread_mutex_init (&object->mylock, &attr);
-@end smallexample
-
-@smallexample
-/* Force no lock elision for a mutex */
-pthread_mutexattr_t attr;
-pthread_mutexattr_init (&attr);
-pthread_mutexattr_setelision_np (&attr, 0);
-pthread_mutex_init (&object->mylock, &attr);
-@end smallexample
-
-Setting a @code{PTHREAD_MUTEX_NORMAL} lock type will also disable elision.
-In some versions of the library any call to @code{pthread_mutexattr_settype} 
-may also disable elision for that lock.
+Support for enabling or disabling elision on a per-lock basis is not currently
+available. The library must be recompiled with elision disabled.
 
 @node Setting elision for individual @code{pthread_rwlock_t}
 @section Setting elision for individual @code{pthread_rwlock_t}
 
-Elision can be explicitly disabled or enabled for each @code{pthread_rwlock_t} in the program using @code{pthread_rwlockattr_setelision_np}.
-
-@smallexample
-/* Force lock elision for a dynamically allocated rwlock */
-pthread_rwlockattr_t rwattr;
-pthread_rwlockattr_init (&rwattr);
-pthread_rwlockattr_setelision_np (&rwattr, 1);
-pthread_rwlock_init (&object->myrwlock, &rwattr);
-@end smallexample
-
+Support for enabling or disabling elision on a per-lock basis is not currently
+available. The library must be recompiled with elision disabled.
---