Messages in this thread Patch in this message | | | Date | Wed, 08 Dec 2021 19:37:00 +0100 | From | Peter Zijlstra <> | Subject | [RFC][PATCH 5/5] atomic: Document the atomic_{}_ofl() functions |
| |
Them special, them cause confusion, them needing docs for reading.
Signed-off-by: Peter Zijlstra (Intel) <peterz@infradead.org> --- Documentation/atomic_t.txt | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+)
--- a/Documentation/atomic_t.txt +++ b/Documentation/atomic_t.txt @@ -44,6 +44,10 @@ The 'full' API consists of (atomic64_ an atomic_add_unless(), atomic_inc_not_zero() atomic_sub_and_test(), atomic_dec_and_test() +Reference count with overflow (as used by refcount_t): + + atomic_inc_ofl(), atomic_dec_ofl() + atomic_dec_and_test_ofl() Misc: @@ -157,6 +161,22 @@ atomic variable) can be fully ordered an visible. +Overflow ops: + +The atomic_{}_ofl() ops are similar to their !_ofl() bretheren with the +notable exception that they take a label as their final argument to jump to +when the atomic op overflows. + +Overflow for inc is zero-or-negative on the value prior to increment. +Overflow for dec is zero-or-negative on the value after the decrement. +Overflow for dec_and_test is negative on the value after the decrement. + +These semantics match the reference count use-case (for which they were +created). Specifically incrementing from zero is a failure because 0 means the +object is freed (IOW use-after-free). decrementing to zero is a failure +because it goes undetected (see dec_and_test) and the object would leak. + + ORDERING (go read memory-barriers.txt first) --------
| |