Whamcloud - gitweb
LU-3059 obdclass: use a dummy structure for lu_ref_link
[fs/lustre-release.git] / lustre / include / lu_ref.h
1 /*
2  * Copyright (c) 2008, 2010, Oracle and/or its affiliates. All rights reserved.
3  * Use is subject to license terms.
4  *
5  * Copyright (c) 2012, Intel Corporation.
6  *
7  *   Author: Nikita Danilov <nikita.danilov@sun.com>
8  *
9  *   This file is part of Lustre, http://www.lustre.org.
10  *
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.
14  *
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.
19  *
20  *   You should have received a copy of the GNU General Public License
21  *   along with Lustre; if not, write to the Free Software
22  *   Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
23  *
24  */
25
26 #ifndef __LUSTRE_LU_REF_H
27 #define __LUSTRE_LU_REF_H
28
29 #include <libcfs/list.h>
30
31 /** \defgroup lu_ref lu_ref
32  *
33  * An interface to track references between objects. Mostly for debugging.
34  *
35  * Suppose there is a reference counted data-structure struct foo. To track
36  * who acquired references to instance of struct foo, add lu_ref field to it:
37  *
38  * \code
39  *         struct foo {
40  *                 atomic_t      foo_refcount;
41  *                 struct lu_ref foo_reference;
42  *                 ...
43  *         };
44  * \endcode
45  *
46  * foo::foo_reference has to be initialized by calling
47  * lu_ref_init(). Typically there will be functions or macros to increment and
48  * decrement foo::foo_refcount, let's say they are foo_get(struct foo *foo)
49  * and foo_put(struct foo *foo), respectively.
50  *
51  * Whenever foo_get() is called to acquire a reference on a foo, lu_ref_add()
52  * has to be called to insert into foo::foo_reference a record, describing
53  * acquired reference. Dually, lu_ref_del() removes matching record. Typical
54  * usages are:
55  *
56  * \code
57  *        struct bar *bar;
58  *
59  *        // bar owns a reference to foo.
60  *        bar->bar_foo = foo_get(foo);
61  *        lu_ref_add(&foo->foo_reference, "bar", bar);
62  *
63  *        ...
64  *
65  *        // reference from bar to foo is released.
66  *        lu_ref_del(&foo->foo_reference, "bar", bar);
67  *        foo_put(bar->bar_foo);
68  *
69  *
70  *        // current thread acquired a temporary reference to foo.
71  *        foo_get(foo);
72  *        lu_ref_add(&foo->reference, __FUNCTION__, cfs_current());
73  *
74  *        ...
75  *
76  *        // temporary reference is released.
77  *        lu_ref_del(&foo->reference, __FUNCTION__, cfs_current());
78  *        foo_put(foo);
79  * \endcode
80  *
81  * \e Et \e cetera. Often it makes sense to include lu_ref_add() and
82  * lu_ref_del() calls into foo_get() and foo_put(). When an instance of struct
83  * foo is destroyed, lu_ref_fini() has to be called that checks that no
84  * pending references remain. lu_ref_print() can be used to dump a list of
85  * pending references, while hunting down a leak.
86  *
87  * For objects to which a large number of references can be acquired,
88  * lu_ref_del() can become cpu consuming, as it has to scan the list of
89  * references. To work around this, remember result of lu_ref_add() (usually
90  * in the same place where pointer to struct foo is stored), and use
91  * lu_ref_del_at():
92  *
93  * \code
94  *        // There is a large number of bar's for a single foo.
95  *        bar->bar_foo     = foo_get(foo);
96  *        bar->bar_foo_ref = lu_ref_add(&foo->foo_reference, "bar", bar);
97  *
98  *        ...
99  *
100  *        // reference from bar to foo is released.
101  *        lu_ref_del_at(&foo->foo_reference, bar->bar_foo_ref, "bar", bar);
102  *        foo_put(bar->bar_foo);
103  * \endcode
104  *
105  * lu_ref interface degrades gracefully in case of memory shortages.
106  *
107  * @{
108  */
109
110 #ifdef USE_LU_REF
111
112 /**
113  * Data-structure to keep track of references to a given object. This is used
114  * for debugging.
115  *
116  * lu_ref is embedded into an object which other entities (objects, threads,
117  * etc.) refer to.
118  */
119 struct lu_ref {
120         /**
121          * Spin-lock protecting lu_ref::lf_list.
122          */
123         spinlock_t              lf_guard;
124         /**
125          * List of all outstanding references (each represented by struct
126          * lu_ref_link), pointing to this object.
127          */
128         cfs_list_t           lf_list;
129         /**
130          * # of links.
131          */
132         short                lf_refs;
133         /**
134          * Flag set when lu_ref_add() failed to allocate lu_ref_link. It is
135          * used to mask spurious failure of the following lu_ref_del().
136          */
137         short                lf_failed;
138         /**
139          * flags - attribute for the lu_ref, for pad and future use.
140          */
141         short                lf_flags;
142         /**
143          * Where was I initialized?
144          */
145         short                lf_line;
146         const char          *lf_func;
147         /**
148          * Linkage into a global list of all lu_ref's (lu_ref_refs).
149          */
150         cfs_list_t           lf_linkage;
151 };
152
153 struct lu_ref_link {
154         struct lu_ref   *ll_ref;
155         cfs_list_t       ll_linkage;
156         const char      *ll_scope;
157         const void      *ll_source;
158 };
159
160 void lu_ref_init_loc(struct lu_ref *ref, const char *func, const int line);
161 void lu_ref_fini    (struct lu_ref *ref);
162 #define lu_ref_init(ref) lu_ref_init_loc(ref, __FUNCTION__, __LINE__)
163
164 void lu_ref_add(struct lu_ref *ref, const char *scope, const void *source);
165
166 void lu_ref_add_atomic(struct lu_ref *ref, const char *scope,
167                        const void *source);
168
169 void lu_ref_add_at(struct lu_ref *ref, struct lu_ref_link *link,
170                    const char *scope, const void *source);
171
172 void lu_ref_del(struct lu_ref *ref, const char *scope, const void *source);
173
174 void lu_ref_set_at(struct lu_ref *ref, struct lu_ref_link *link,
175                    const char *scope, const void *source0, const void *source1);
176
177 void lu_ref_del_at(struct lu_ref *ref, struct lu_ref_link *link,
178                    const char *scope, const void *source);
179
180 void lu_ref_print(const struct lu_ref *ref);
181
182 void lu_ref_print_all(void);
183
184 int lu_ref_global_init(void);
185
186 void lu_ref_global_fini(void);
187
188 #else /* !USE_LU_REF */
189
190 struct lu_ref {
191 };
192
193 struct lu_ref_link {
194 };
195
196 static inline void lu_ref_init(struct lu_ref *ref)
197 {
198 }
199
200 static inline void lu_ref_fini(struct lu_ref *ref)
201 {
202 }
203
204 static inline void lu_ref_add(struct lu_ref *ref,
205                               const char *scope,
206                               const void *source)
207 {
208 }
209
210 static inline void lu_ref_add_atomic(struct lu_ref *ref,
211                                      const char *scope,
212                                      const void *source)
213 {
214 }
215
216 static inline void lu_ref_add_at(struct lu_ref *ref,
217                                  struct lu_ref_link *link,
218                                  const char *scope,
219                                  const void *source)
220 {
221 }
222
223 static inline void lu_ref_del(struct lu_ref *ref, const char *scope,
224                               const void *source)
225 {
226 }
227
228 static inline void lu_ref_set_at(struct lu_ref *ref, struct lu_ref_link *link,
229                                  const char *scope, const void *source0,
230                                  const void *source1)
231 {
232 }
233
234 static inline void lu_ref_del_at(struct lu_ref *ref, struct lu_ref_link *link,
235                                  const char *scope, const void *source)
236 {
237 }
238
239 static inline int lu_ref_global_init(void)
240 {
241         return 0;
242 }
243
244 static inline void lu_ref_global_fini(void)
245 {
246 }
247
248 static inline void lu_ref_print(const struct lu_ref *ref)
249 {
250 }
251
252 static inline void lu_ref_print_all(void)
253 {
254 }
255 #endif /* USE_LU_REF */
256
257 /** @} lu */
258
259 #endif /* __LUSTRE_LU_REF_H */