Commit d1bbfd0c authored by Peter Zijlstra's avatar Peter Zijlstra
Browse files

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: default avatarPeter Zijlstra (Intel) <peterz@infradead.org>
Acked-by: default avatarWill Deacon <will@kernel.org>
Link: https://lkml.kernel.org/r/YOMgPeMOmmiK3tXO@hirez.programming.kicks-ass.net
parent e6b4457b

Documentation/atomic_t.txt

+41 −0
Original line number Diff line number Diff line
@@ -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.