include/linux/kref.h

1 /* SPDX-License-Identifier: GPL-2.0-only */
3  * kref.h - library routines for handling generic reference counted objects
5  * Copyright (C) 2004 Greg Kroah-Hartman <greg@kroah.com>
9  * Copyright (C) 2002-2003 Patrick Mochel <mochel@osdl.org>
10  * Copyright (C) 2002-2003 Open Source Development Labs
26  * kref_init - initialize object.
27  * @kref: object in question.
31 	refcount_set(&kref->refcount, 1);  in kref_init()
36 	return refcount_read(&kref->refcount);  in kref_read()
40  * kref_get - increment refcount for object.
45 	refcount_inc(&kref->refcount);  in kref_get()
49  * kref_put - decrement refcount for object.
53  *	     This pointer is required, and it is not acceptable to pass kfree
54  *	     in as this function.
56  * Decrement the refcount, and if 0, call release().
58  * function returns 0, you still can not count on the kref from remaining in
64 	if (refcount_dec_and_test(&kref->refcount)) {  in kref_put()
75 	if (refcount_dec_and_mutex_lock(&kref->refcount, lock)) {  in kref_put_mutex()
86 	if (refcount_dec_and_lock(&kref->refcount, lock)) {  in kref_put_lock()
94  * kref_get_unless_zero - Increment refcount for object unless it is zero.
97  * Return non-zero if the increment succeeded. Otherwise return 0.
99  * This function is intended to simplify locking around refcounting for
100  * objects that can be looked up from a lookup structure, and which are
101  * removed from that lookup structure in the object destructor.
102  * Operations on such objects require at least a read lock around
103  * lookup + kref_get, and a write lock around kref_put + remove from lookup
106  * locking in the kref_put path can be deferred to the actual removal from
107  * the lookup structure and RCU lookups become trivial.
111 	return refcount_inc_not_zero(&kref->refcount);  in kref_get_unless_zero()