This is the mail archive of the
libc-alpha@sourceware.org
mailing list for the glibc project.
Re: [PATCH 08/14] Add manual for lock elision
- From: "Carlos O'Donell" <carlos at redhat dot com>
- To: Andi Kleen <andi at firstfloor dot org>
- Cc: libc-alpha at sourceware dot org, Andi Kleen <ak at linux dot jf dot intel dot com>
- Date: Fri, 28 Jun 2013 13:12:31 -0400
- Subject: Re: [PATCH 08/14] Add manual for lock elision
- References: <1372398717-16530-1-git-send-email-andi at firstfloor dot org> <1372398717-16530-9-git-send-email-andi at firstfloor dot org> <51CD44B5 dot 5000202 at redhat dot com> <20130628145037 dot GU6123 at two dot firstfloor dot org>
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.
---