2 * Copyright (c) 2008, 2010, Oracle and/or its affiliates. All rights reserved.
3 * Use is subject to license terms.
5 * Copyright (c) 2012, Intel Corporation.
7 * Author: Nikita Danilov <nikita.danilov@sun.com>
9 * This file is part of Lustre, http://www.lustre.org.
11 * Lustre is free software; you can redistribute it and/or
12 * modify it under the terms of version 2 of the GNU General Public
13 * License as published by the Free Software Foundation.
15 * Lustre is distributed in the hope that it will be useful,
16 * but WITHOUT ANY WARRANTY; without even the implied warranty of
17 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
18 * GNU General Public License for more details.
22 #ifndef __LUSTRE_LU_REF_H
23 #define __LUSTRE_LU_REF_H
25 #include <linux/list.h>
27 /** \defgroup lu_ref lu_ref
29 * An interface to track references between objects. Mostly for debugging.
31 * Suppose there is a reference counted data-structure struct foo. To track
32 * who acquired references to instance of struct foo, add lu_ref field to it:
36 * atomic_t foo_refcount;
37 * struct lu_ref foo_reference;
42 * foo::foo_reference has to be initialized by calling
43 * lu_ref_init(). Typically there will be functions or macros to increment and
44 * decrement foo::foo_refcount, let's say they are foo_get(struct foo *foo)
45 * and foo_put(struct foo *foo), respectively.
47 * Whenever foo_get() is called to acquire a reference on a foo, lu_ref_add()
48 * has to be called to insert into foo::foo_reference a record, describing
49 * acquired reference. Dually, lu_ref_del() removes matching record. Typical
55 * // bar owns a reference to foo.
56 * bar->bar_foo = foo_get(foo);
57 * lu_ref_add(&foo->foo_reference, "bar", bar);
61 * // reference from bar to foo is released.
62 * lu_ref_del(&foo->foo_reference, "bar", bar);
63 * foo_put(bar->bar_foo);
66 * // current thread acquired a temporary reference to foo.
68 * lu_ref_add(&foo->reference, __func__, current);
72 * // temporary reference is released.
73 * lu_ref_del(&foo->reference, __func__, current);
77 * \e Et \e cetera. Often it makes sense to include lu_ref_add() and
78 * lu_ref_del() calls into foo_get() and foo_put(). When an instance of struct
79 * foo is destroyed, lu_ref_fini() has to be called that checks that no
80 * pending references remain. lu_ref_print() can be used to dump a list of
81 * pending references, while hunting down a leak.
83 * For objects to which a large number of references can be acquired,
84 * lu_ref_del() can become cpu consuming, as it has to scan the list of
85 * references. To work around this, remember result of lu_ref_add() (usually
86 * in the same place where pointer to struct foo is stored), and use
90 * // There is a large number of bar's for a single foo.
91 * bar->bar_foo = foo_get(foo);
92 * bar->bar_foo_ref = lu_ref_add(&foo->foo_reference, "bar", bar);
96 * // reference from bar to foo is released.
97 * lu_ref_del_at(&foo->foo_reference, bar->bar_foo_ref, "bar", bar);
98 * foo_put(bar->bar_foo);
101 * lu_ref interface degrades gracefully in case of memory shortages.
107 * dummy data structures/functions to pass compile for now.
108 * We need to reimplement them with kref.
111 struct lu_ref_link {};
113 static inline void lu_ref_init(struct lu_ref *ref)
117 static inline void lu_ref_fini(struct lu_ref *ref)
121 static inline struct lu_ref_link *lu_ref_add(struct lu_ref *ref,
128 static inline struct lu_ref_link *lu_ref_add_atomic(struct lu_ref *ref,
135 static inline void lu_ref_add_at(struct lu_ref *ref,
136 struct lu_ref_link *link,
142 static inline void lu_ref_del(struct lu_ref *ref, const char *scope,
147 static inline void lu_ref_set_at(struct lu_ref *ref, struct lu_ref_link *link,
148 const char *scope, const void *source0,
153 static inline void lu_ref_del_at(struct lu_ref *ref, struct lu_ref_link *link,
154 const char *scope, const void *source)
158 static inline int lu_ref_global_init(void)
163 static inline void lu_ref_global_fini(void)
167 static inline void lu_ref_print(const struct lu_ref *ref)
171 static inline void lu_ref_print_all(void)
177 #endif /* __LUSTRE_LU_REF_H */