| 1 | /* SPDX-License-Identifier: GPL-2.0-only */ |
|---|
| 2 | /* |
|---|
| 3 | * kref.h - library routines for handling generic reference counted objects |
|---|
| 4 | * |
|---|
| 5 | * Copyright (C) 2004 Greg Kroah-Hartman <greg@kroah.com> |
|---|
| 6 | * Copyright (C) 2004 IBM Corp. |
|---|
| 7 | * |
|---|
| 8 | * based on kobject.h which was: |
|---|
| 9 | * Copyright (C) 2002-2003 Patrick Mochel <mochel@osdl.org> |
|---|
| 10 | * Copyright (C) 2002-2003 Open Source Development Labs |
|---|
| 11 | */ |
|---|
| 12 | |
|---|
| 13 | #ifndef _KREF_H_ |
|---|
| 14 | #define _KREF_H_ |
|---|
| 15 | |
|---|
| 16 | #include <linux/spinlock.h> |
|---|
| 17 | #include <linux/refcount.h> |
|---|
| 18 | |
|---|
| 19 | struct kref { |
|---|
| 20 | refcount_t refcount; |
|---|
| 21 | }; |
|---|
| 22 | |
|---|
| 23 | #define KREF_INIT(n) { .refcount = REFCOUNT_INIT(n), } |
|---|
| 24 | |
|---|
| 25 | /** |
|---|
| 26 | * kref_init - initialize object. |
|---|
| 27 | * @kref: object in question. |
|---|
| 28 | */ |
|---|
| 29 | static inline void kref_init(struct kref *kref) |
|---|
| 30 | { |
|---|
| 31 | refcount_set(r: &kref->refcount, n: 1); |
|---|
| 32 | } |
|---|
| 33 | |
|---|
| 34 | static inline unsigned int kref_read(const struct kref *kref) |
|---|
| 35 | { |
|---|
| 36 | return refcount_read(r: &kref->refcount); |
|---|
| 37 | } |
|---|
| 38 | |
|---|
| 39 | /** |
|---|
| 40 | * kref_get - increment refcount for object. |
|---|
| 41 | * @kref: object. |
|---|
| 42 | */ |
|---|
| 43 | static inline void kref_get(struct kref *kref) |
|---|
| 44 | { |
|---|
| 45 | refcount_inc(r: &kref->refcount); |
|---|
| 46 | } |
|---|
| 47 | |
|---|
| 48 | /** |
|---|
| 49 | * kref_put - Decrement refcount for object |
|---|
| 50 | * @kref: Object |
|---|
| 51 | * @release: Pointer to the function that will clean up the object when the |
|---|
| 52 | * last reference to the object is released. |
|---|
| 53 | * |
|---|
| 54 | * Decrement the refcount, and if 0, call @release. The caller may not |
|---|
| 55 | * pass NULL or kfree() as the release function. |
|---|
| 56 | * |
|---|
| 57 | * Return: 1 if this call removed the object, otherwise return 0. Beware, |
|---|
| 58 | * if this function returns 0, another caller may have removed the object |
|---|
| 59 | * by the time this function returns. The return value is only certain |
|---|
| 60 | * if you want to see if the object is definitely released. |
|---|
| 61 | */ |
|---|
| 62 | static inline int kref_put(struct kref *kref, void (*release)(struct kref *kref)) |
|---|
| 63 | { |
|---|
| 64 | if (refcount_dec_and_test(r: &kref->refcount)) { |
|---|
| 65 | release(kref); |
|---|
| 66 | return 1; |
|---|
| 67 | } |
|---|
| 68 | return 0; |
|---|
| 69 | } |
|---|
| 70 | |
|---|
| 71 | /** |
|---|
| 72 | * kref_put_mutex - Decrement refcount for object |
|---|
| 73 | * @kref: Object |
|---|
| 74 | * @release: Pointer to the function that will clean up the object when the |
|---|
| 75 | * last reference to the object is released. |
|---|
| 76 | * @mutex: Mutex which protects the release function. |
|---|
| 77 | * |
|---|
| 78 | * This variant of kref_lock() calls the @release function with the @mutex |
|---|
| 79 | * held. The @release function will release the mutex. |
|---|
| 80 | */ |
|---|
| 81 | static inline int kref_put_mutex(struct kref *kref, |
|---|
| 82 | void (*release)(struct kref *kref), |
|---|
| 83 | struct mutex *mutex) |
|---|
| 84 | { |
|---|
| 85 | if (refcount_dec_and_mutex_lock(r: &kref->refcount, lock: mutex)) { |
|---|
| 86 | release(kref); |
|---|
| 87 | return 1; |
|---|
| 88 | } |
|---|
| 89 | return 0; |
|---|
| 90 | } |
|---|
| 91 | |
|---|
| 92 | /** |
|---|
| 93 | * kref_put_lock - Decrement refcount for object |
|---|
| 94 | * @kref: Object |
|---|
| 95 | * @release: Pointer to the function that will clean up the object when the |
|---|
| 96 | * last reference to the object is released. |
|---|
| 97 | * @lock: Spinlock which protects the release function. |
|---|
| 98 | * |
|---|
| 99 | * This variant of kref_lock() calls the @release function with the @lock |
|---|
| 100 | * held. The @release function will release the lock. |
|---|
| 101 | */ |
|---|
| 102 | static inline int kref_put_lock(struct kref *kref, |
|---|
| 103 | void (*release)(struct kref *kref), |
|---|
| 104 | spinlock_t *lock) |
|---|
| 105 | { |
|---|
| 106 | if (refcount_dec_and_lock(r: &kref->refcount, lock)) { |
|---|
| 107 | release(kref); |
|---|
| 108 | return 1; |
|---|
| 109 | } |
|---|
| 110 | return 0; |
|---|
| 111 | } |
|---|
| 112 | |
|---|
| 113 | /** |
|---|
| 114 | * kref_get_unless_zero - Increment refcount for object unless it is zero. |
|---|
| 115 | * @kref: object. |
|---|
| 116 | * |
|---|
| 117 | * This function is intended to simplify locking around refcounting for |
|---|
| 118 | * objects that can be looked up from a lookup structure, and which are |
|---|
| 119 | * removed from that lookup structure in the object destructor. |
|---|
| 120 | * Operations on such objects require at least a read lock around |
|---|
| 121 | * lookup + kref_get, and a write lock around kref_put + remove from lookup |
|---|
| 122 | * structure. Furthermore, RCU implementations become extremely tricky. |
|---|
| 123 | * With a lookup followed by a kref_get_unless_zero *with return value check* |
|---|
| 124 | * locking in the kref_put path can be deferred to the actual removal from |
|---|
| 125 | * the lookup structure and RCU lookups become trivial. |
|---|
| 126 | * |
|---|
| 127 | * Return: non-zero if the increment succeeded. Otherwise return 0. |
|---|
| 128 | */ |
|---|
| 129 | static inline int __must_check kref_get_unless_zero(struct kref *kref) |
|---|
| 130 | { |
|---|
| 131 | return refcount_inc_not_zero(r: &kref->refcount); |
|---|
| 132 | } |
|---|
| 133 | #endif /* _KREF_H_ */ |
|---|
| 134 | |
|---|
