include/linux/kref.h

   1 /*
   2  * kref.h - library routines for handling generic reference counted objects
   3  *
   4  * Copyright (C) 2004 Greg Kroah-Hartman <greg@kroah.com>
   5  * Copyright (C) 2004 IBM Corp.
   6  *
   7  * based on kobject.h which was:
   8  * Copyright (C) 2002-2003 Patrick Mochel <mochel@osdl.org>
   9  * Copyright (C) 2002-2003 Open Source Development Labs
  10  *
  11  * This file is released under the GPLv2.
  12  *
  13  */
  14
  15 #ifndef _KREF_H_
  16 #define _KREF_H_
  17
  18 #include <linux/bug.h>
  19 #include <linux/atomic.h>
  20 #include <linux/kernel.h>
  21 #include <linux/mutex.h>
  22 #include <linux/spinlock.h>
  23
  24 struct kref {
  25         atomic_t refcount;
  26 };
  27
  28 #define KREF_INIT(n)    { .refcount = ATOMIC_INIT(n), }
  29
  30 /**
  31  * kref_init - initialize object.
  32  * @kref: object in question.
  33  */
  34 static inline void kref_init(struct kref *kref)
  35 {
  36         atomic_set(&kref->refcount, 1);
  37 }
  38
  39 static inline int kref_read(const struct kref *kref)
  40 {
  41         return atomic_read(&kref->refcount);
  42 }
  43
  44 /**
  45  * kref_get - increment refcount for object.
  46  * @kref: object.
  47  */
  48 static inline void kref_get(struct kref *kref)
  49 {
  50         /* If refcount was 0 before incrementing then we have a race
  51          * condition when this kref is freeing by some other thread right now.
  52          * In this case one should use kref_get_unless_zero()
  53          */
  54         WARN_ON_ONCE(atomic_inc_return(&kref->refcount) < 2);
  55 }
  56
  57 /**
  58  * kref_put - decrement refcount for object.
  59  * @kref: object.
  60  * @release: pointer to the function that will clean up the object when the
  61  *           last reference to the object is released.
  62  *           This pointer is required, and it is not acceptable to pass kfree
  63  *           in as this function.  If the caller does pass kfree to this
  64  *           function, you will be publicly mocked mercilessly by the kref
  65  *           maintainer, and anyone else who happens to notice it.  You have
  66  *           been warned.
  67  *
  68  * Decrement the refcount, and if 0, call release().
  69  * Return 1 if the object was removed, otherwise return 0.  Beware, if this
  70  * function returns 0, you still can not count on the kref from remaining in
  71  * memory.  Only use the return value if you want to see if the kref is now
  72  * gone, not present.
  73  */
  74 static inline int kref_put(struct kref *kref, void (*release)(struct kref *kref))
  75 {
  76         WARN_ON(release == NULL);
  77
  78         if (atomic_dec_and_test(&kref->refcount)) {
  79                 release(kref);
  80                 return 1;
  81         }
  82         return 0;
  83 }
  84
  85 static inline int kref_put_mutex(struct kref *kref,
  86                                  void (*release)(struct kref *kref),
  87                                  struct mutex *lock)
  88 {
  89         WARN_ON(release == NULL);
  90
  91         if (atomic_dec_and_mutex_lock(&kref->refcount, lock)) {
  92                 release(kref);
  93                 return 1;
  94         }
  95         return 0;
  96 }
  97
  98 static inline int kref_put_lock(struct kref *kref,
  99                                 void (*release)(struct kref *kref),
 100                                 spinlock_t *lock)
 101 {
 102         WARN_ON(release == NULL);
 103
 104         if (atomic_dec_and_lock(&kref->refcount, lock)) {
 105                 release(kref);
 106                 return 1;
 107         }
 108         return 0;
 109 }
 110
 111 /**
 112  * kref_get_unless_zero - Increment refcount for object unless it is zero.
 113  * @kref: object.
 114  *
 115  * Return non-zero if the increment succeeded. Otherwise return 0.
 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 static inline int __must_check kref_get_unless_zero(struct kref *kref)
 128 {
 129         return atomic_add_unless(&kref->refcount, 1, 0);
 130 }
 131 #endif /* _KREF_H_ */