include/linux/refcount.h

1 /* SPDX-License-Identifier: GPL-2.0 */
6  * provides the few functions one should use for reference counting.
13  * counter and causing 'spurious' use-after-free issues. In order to avoid the
23  *   +--------------------------------+----------------+----------------+
24  *                                     <---------- bad value! ---------->
50  *     (UINT_MAX+1-REFCOUNT_SATURATED) / PID_MAX_LIMIT =
55  * given the precise timing details involved with the round-robin scheduling of
82  * because the 1->0 transition indicates no concurrency.
91  * acquire and release ordering for cases when the memory occupied by the
93  * cases where secondary validation is required to detect such reuse, e.g.
128  * refcount_set - set a refcount's value
134 	atomic_set(&r->refs, n);  in refcount_set()
138  * refcount_set_release - set a refcount's value with release ordering
143  * reused to store another object -- consider SLAB_TYPESAFE_BY_RCU.
159 	atomic_set_release(&r->refs, n);  in refcount_set_release()
163  * refcount_read - get a refcount's value
170 	return atomic_read(&r->refs);  in refcount_read()
181 	} while (!atomic_try_cmpxchg_relaxed(&r->refs, &old, old + i));  in __refcount_add_not_zero()
193  * refcount_add_not_zero - add a value to a refcount unless it is 0
203  * Use of this function is not recommended for the normal reference counting
204  * use case in which references are taken and released one at a time.  In these
205  * cases, refcount_inc(), or one of its variants, should instead be used to
225 		if (i > limit - old) {  in __refcount_add_not_zero_limited_acquire()
230 	} while (!atomic_try_cmpxchg_acquire(&r->refs, &old, old + i));  in __refcount_add_not_zero_limited_acquire()
254  * refcount_add_not_zero_acquire - add a value to a refcount with acquire ordering unless it is 0
262  * reused to store another object -- consider SLAB_TYPESAFE_BY_RCU.
268  * Use of this function is not recommended for the normal reference counting
269  * use case in which references are taken and released one at a time.  In these
270  * cases, refcount_inc_not_zero_acquire() should instead be used to increment a
283 	int old = atomic_fetch_add_relaxed(i, &r->refs);  in __refcount_add()
295  * refcount_add - add a value to a refcount
305  * Use of this function is not recommended for the normal reference counting
306  * use case in which references are taken and released one at a time.  In these
307  * cases, refcount_inc(), or one of its variants, should instead be used to
321  * refcount_inc_not_zero - increment a refcount unless it is 0
344  * refcount_inc_not_zero_acquire - increment a refcount with acquire ordering unless it is 0
351  * reused to store another object -- consider SLAB_TYPESAFE_BY_RCU.
370  * refcount_inc - increment a refcount
378  * Will WARN if the refcount is 0, as this represents a possible use-after-free
389 	int old = atomic_fetch_sub_release(i, &r->refs);  in __refcount_sub_and_test()
399 	if (unlikely(old <= 0 || old - i < 0))  in __refcount_sub_and_test()
406  * refcount_sub_and_test - subtract from a refcount and test if it is 0
418  * Use of this function is not recommended for the normal reference counting
419  * use case in which references are taken and released one at a time.  In these
420  * cases, refcount_dec(), or one of its variants, should instead be used to
436  * refcount_dec_and_test - decrement a refcount and test if it is 0
455 	int old = atomic_fetch_sub_release(1, &r->refs);  in __refcount_dec()
465  * refcount_dec - decrement a refcount