The following commit has been merged into the locking/core branch of tip: Commit-ID: d1bbfd0c7c9f985e57795a7e0cefc209ebf689c0 Gitweb: https://git.kernel.org/tip/d1bbfd0c7c9f985e57795a7e0cefc209ebf689c0 Author: Peter Zijlstra <peterz@xxxxxxxxxxxxx> AuthorDate: Mon, 05 Jul 2021 17:00:24 +02:00 Committer: Peter Zijlstra <peterz@xxxxxxxxxxxxx> CommitterDate: Wed, 07 Jul 2021 13:53:25 +02:00 Documentation/atomic_t: Document cmpxchg() vs try_cmpxchg() There seems to be a significant amount of confusion around the new try_cmpxchg(), despite this being more like the C11 atomic_compare_exchange_*() family. Add a few words of clarification on how cmpxchg() and try_cmpxchg() relate to one another. Signed-off-by: Peter Zijlstra (Intel) <peterz@xxxxxxxxxxxxx> Acked-by: Will Deacon <will@xxxxxxxxxx> Link: https://lkml.kernel.org/r/YOMgPeMOmmiK3tXO@xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx --- Documentation/atomic_t.txt | 41 +++++++++++++++++++++++++++++++++++++- 1 file changed, 41 insertions(+) diff --git a/Documentation/atomic_t.txt b/Documentation/atomic_t.txt index 0f1fded..a9c1e2b 100644 --- a/Documentation/atomic_t.txt +++ b/Documentation/atomic_t.txt @@ -271,3 +271,44 @@ WRITE_ONCE. Thus: SC *y, t; is allowed. + + +CMPXCHG vs TRY_CMPXCHG +---------------------- + + int atomic_cmpxchg(atomic_t *ptr, int old, int new); + bool atomic_try_cmpxchg(atomic_t *ptr, int *oldp, int new); + +Both provide the same functionality, but try_cmpxchg() can lead to more +compact code. The functions relate like: + + bool atomic_try_cmpxchg(atomic_t *ptr, int *oldp, int new) + { + int ret, old = *oldp; + ret = atomic_cmpxchg(ptr, old, new); + if (ret != old) + *oldp = ret; + return ret == old; + } + +and: + + int atomic_cmpxchg(atomic_t *ptr, int old, int new) + { + (void)atomic_try_cmpxchg(ptr, &old, new); + return old; + } + +Usage: + + old = atomic_read(&v); old = atomic_read(&v); + for (;;) { do { + new = func(old); new = func(old); + tmp = atomic_cmpxchg(&v, old, new); } while (!atomic_try_cmpxchg(&v, &old, new)); + if (tmp == old) + break; + old = tmp; + } + +NB. try_cmpxchg() also generates better code on some platforms (notably x86) +where the function more closely matches the hardware instruction.
![]() |