Motr  M0
list.h
Go to the documentation of this file.
1 /* -*- C -*- */
2 /*
3  * Copyright (c) 2013-2020 Seagate Technology LLC and/or its Affiliates
4  *
5  * Licensed under the Apache License, Version 2.0 (the "License");
6  * you may not use this file except in compliance with the License.
7  * You may obtain a copy of the License at
8  *
9  * http://www.apache.org/licenses/LICENSE-2.0
10  *
11  * Unless required by applicable law or agreed to in writing, software
12  * distributed under the License is distributed on an "AS IS" BASIS,
13  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14  * See the License for the specific language governing permissions and
15  * limitations under the License.
16  *
17  * For any questions about this software or licensing,
18  * please email opensource@seagate.com or cortx-questions@seagate.com.
19  *
20  */
21 
22 
23 #pragma once
24 #ifndef __MOTR_BE_LIST_H__
25 #define __MOTR_BE_LIST_H__
26 
27 #include "format/format.h" /* m0_format_header */
28 #include "format/format_xc.h"
29 
30 /* import */
31 struct m0_be_tx;
32 struct m0_be_tx_credit;
33 
46 enum m0_be_list_format_version {
47  M0_BE_LIST_FORMAT_VERSION_1 = 1,
48 
49  /* future versions, uncomment and update M0_BE_LIST_FORMAT_VERSION */
50  /*M0_BE_LIST_FORMAT_VERSION_2,*/
51  /*M0_BE_LIST_FORMAT_VERSION_3,*/
52 
54  M0_BE_LIST_FORMAT_VERSION = M0_BE_LIST_FORMAT_VERSION_1
55 };
56 
57 struct m0_be_list_descr {
58  const char *bld_name;
59  int bld_link_offset;
60  int bld_link_magic_offset;
61  uint64_t bld_link_magic;
62  uint64_t bld_head_magic;
63  size_t bld_container_size;
64 };
65 
66 struct m0_be_list_link {
67  struct m0_be_list_link *bll_next;
68  struct m0_be_list_link *bll_prev;
69 } M0_XCA_RECORD M0_XCA_DOMAIN(be);
70 
71 struct m0_be_list_head {
72  struct m0_be_list_link *blh_head;
73  struct m0_be_list_link *blh_tail;
74 } M0_XCA_RECORD M0_XCA_DOMAIN(be);
75 
76 struct m0_be_list {
77  struct m0_format_header bl_format_header;
78  struct m0_be_list_head bl_head;
79  uint64_t bl_magic;
80  struct m0_format_footer bl_format_footer;
81 } M0_XCA_RECORD M0_XCA_DOMAIN(be);
82 
84 enum m0_be_list_op {
85  M0_BLO_CREATE,
86  M0_BLO_DESTROY,
87  M0_BLO_ADD,
91  M0_BLO_DEL,
92  M0_BLO_TLINK_CREATE,
93  M0_BLO_TLINK_DESTROY,
94  M0_BLO_NR
95 };
96 
101 M0_INTERNAL void m0_be_list_credit(enum m0_be_list_op optype,
102  m0_bcount_t nr,
103  struct m0_be_tx_credit *accum);
104 
105 /* -------------------------------------------------------------------------
106  * Construction/Destruction:
107  * ------------------------------------------------------------------------- */
108 
109 M0_INTERNAL void m0_be_list_create(struct m0_be_list *blist,
110  const struct m0_be_list_descr *descr,
111  struct m0_be_tx *tx);
112 M0_INTERNAL void m0_be_list_destroy(struct m0_be_list *blist,
113  const struct m0_be_list_descr *descr,
114  struct m0_be_tx *tx);
115 
116 M0_INTERNAL bool m0_be_list_is_empty(struct m0_be_list *blist,
117  const struct m0_be_list_descr *descr);
118 
119 /* m0_be_link_*() functions follow BE naming pattern and not m0_tlist naming. */
120 M0_INTERNAL void m0_be_tlink_create(void *obj,
121  const struct m0_be_list_descr *descr,
122  struct m0_be_tx *tx);
123 M0_INTERNAL void m0_be_tlink_destroy(void *obj,
124  const struct m0_be_list_descr *descr,
125  struct m0_be_tx *tx);
126 
127 
128 /* -------------------------------------------------------------------------
129  * Iteration interfaces:
130  * ------------------------------------------------------------------------- */
131 
132 M0_INTERNAL void *m0_be_list_tail(struct m0_be_list *blist,
133  const struct m0_be_list_descr *descr);
134 
135 M0_INTERNAL void *m0_be_list_head(struct m0_be_list *blist,
136  const struct m0_be_list_descr *descr);
137 
138 M0_INTERNAL void *m0_be_list_prev(struct m0_be_list *blist,
139  const struct m0_be_list_descr *descr,
140  const void *obj);
141 
142 M0_INTERNAL void *m0_be_list_next(struct m0_be_list *blist,
143  const struct m0_be_list_descr *descr,
144  const void *obj);
145 
146 /* -------------------------------------------------------------------------
147  * Modification interfaces:
148  * ------------------------------------------------------------------------- */
149 
150 M0_INTERNAL void m0_be_list_add(struct m0_be_list *blist,
151  const struct m0_be_list_descr *descr,
152  struct m0_be_tx *tx,
153  void *obj);
154 
155 M0_INTERNAL void m0_be_list_add_after(struct m0_be_list *blist,
156  const struct m0_be_list_descr *descr,
157  struct m0_be_tx *tx,
158  void *obj,
159  void *obj_new);
160 
161 M0_INTERNAL void m0_be_list_add_before(struct m0_be_list *blist,
162  const struct m0_be_list_descr *descr,
163  struct m0_be_tx *tx,
164  void *obj,
165  void *obj_new);
166 
167 M0_INTERNAL void m0_be_list_add_tail(struct m0_be_list *blist,
168  const struct m0_be_list_descr *descr,
169  struct m0_be_tx *tx,
170  void *obj);
171 
172 M0_INTERNAL void m0_be_list_del(struct m0_be_list *blist,
173  const struct m0_be_list_descr *descr,
174  struct m0_be_tx *tx,
175  void *obj);
176 
177 /* -------------------------------------------------------------------------
178  * Type-safe macros:
179  * ------------------------------------------------------------------------- */
180 
184 #define M0_BE_LIST_DESCR(name, amb_type, link_field, magic_field, \
185  link_magic, head_magic) \
186 { \
187  .bld_name = name, \
188  .bld_link_offset = offsetof(amb_type, link_field), \
189  .bld_link_magic_offset = offsetof(amb_type, magic_field), \
190  .bld_link_magic = link_magic, \
191  .bld_head_magic = head_magic, \
192  .bld_container_size = sizeof(amb_type), \
193 }; \
194 M0_BASSERT(M0_HAS_TYPE(M0_FIELD_VALUE(amb_type, link_field), \
195  struct m0_be_list_link)); \
196 M0_BASSERT(M0_HAS_TYPE(M0_FIELD_VALUE(amb_type, magic_field), \
197  uint64_t))
198 
202 #define M0_BE_LIST_DESCR_DEFINE(name, hname, scope, amb_type, link_field, \
203  magic_field, link_magic, head_magic) \
204 scope const struct m0_be_list_descr name ## _be_list_d = \
205  M0_BE_LIST_DESCR(hname, amb_type, link_field, magic_field, \
206  link_magic, head_magic)
207 
211 #define M0_BE_LIST_DECLARE(name, scope, amb_type) \
212  \
213 scope void name ## _be_list_credit(enum m0_be_list_op optype, \
214  m0_bcount_t nr, \
215  struct m0_be_tx_credit *accum); \
216 scope void name ## _be_list_create(struct m0_be_list *blist, \
217  struct m0_be_tx *tx); \
218 scope void name ## _be_list_destroy(struct m0_be_list *blist, \
219  struct m0_be_tx *tx); \
220 scope bool name ## _be_list_is_empty(struct m0_be_list *blist); \
221 scope void name ## _be_tlink_create(amb_type *obj, \
222  struct m0_be_tx *tx); \
223 scope void name ## _be_tlink_destroy(amb_type *obj, \
224  struct m0_be_tx *tx); \
225 scope amb_type *name ## _be_list_tail(struct m0_be_list *blist); \
226 scope amb_type *name ## _be_list_head(struct m0_be_list *blist); \
227 scope amb_type *name ## _be_list_prev(struct m0_be_list *blist, \
228  const amb_type *obj); \
229 scope amb_type *name ## _be_list_next(struct m0_be_list *blist, \
230  const amb_type *obj); \
231 scope void name ## _be_list_add(struct m0_be_list *blist, \
232  struct m0_be_tx *tx, \
233  amb_type *obj); \
234 scope void name ## _be_list_add_after(struct m0_be_list *blist, \
235  struct m0_be_tx *tx, \
236  amb_type *obj, \
237  amb_type *obj_new); \
238 scope void name ## _be_list_add_before(struct m0_be_list *blist, \
239  struct m0_be_tx *tx, \
240  amb_type *obj, \
241  amb_type *obj_new); \
242 scope void name ## _be_list_add_tail(struct m0_be_list *blist, \
243  struct m0_be_tx *tx, \
244  amb_type *obj); \
245 scope void name ## _be_list_del(struct m0_be_list *blist, \
246  struct m0_be_tx *tx, \
247  amb_type *obj)
248 
249 
253 #define M0_BE_LIST_DEFINE(name, scope, amb_type) \
254  \
255 scope M0_UNUSED void name ## _be_list_credit(enum m0_be_list_op optype, \
256  m0_bcount_t nr, \
257  struct m0_be_tx_credit *accum) \
258 { \
259  m0_be_list_credit(optype, nr, accum); \
260 } \
261  \
262 scope M0_UNUSED void name ## _be_list_create(struct m0_be_list *blist, \
263  struct m0_be_tx *tx) \
264 { \
265  m0_be_list_create(blist, &name ## _be_list_d, tx); \
266 } \
267  \
268 scope M0_UNUSED void name ## _be_list_destroy(struct m0_be_list *blist, \
269  struct m0_be_tx *tx) \
270 { \
271  m0_be_list_destroy(blist, &name ## _be_list_d, tx); \
272 } \
273  \
274 scope M0_UNUSED bool name ## _be_list_is_empty(struct m0_be_list *blist) \
275 { \
276  return m0_be_list_is_empty(blist, &name ## _be_list_d); \
277 } \
278  \
279 scope M0_UNUSED void name ## _be_tlink_create(amb_type *obj, \
280  struct m0_be_tx *tx) \
281 { \
282  m0_be_tlink_create(obj, &name ## _be_list_d, tx); \
283 } \
284  \
285 scope M0_UNUSED void name ## _be_tlink_destroy(amb_type *obj, \
286  struct m0_be_tx *tx) \
287 { \
288  m0_be_tlink_destroy(obj, &name ## _be_list_d, tx); \
289 } \
290  \
291 scope M0_UNUSED amb_type *name ## _be_list_tail(struct m0_be_list *blist) \
292 { \
293  return (amb_type *)m0_be_list_tail(blist, &name ## _be_list_d); \
294 } \
295  \
296 scope M0_UNUSED amb_type *name ## _be_list_head(struct m0_be_list *blist) \
297 { \
298  return (amb_type *)m0_be_list_head(blist, &name ## _be_list_d); \
299 } \
300  \
301 scope M0_UNUSED amb_type *name ## _be_list_prev(struct m0_be_list *blist, \
302  const amb_type *obj) \
303 { \
304  return (amb_type *)m0_be_list_prev(blist, &name ## _be_list_d, obj); \
305 } \
306  \
307 scope M0_UNUSED amb_type *name ## _be_list_next(struct m0_be_list *blist, \
308  const amb_type *obj) \
309 { \
310  return (amb_type *)m0_be_list_next(blist, &name ## _be_list_d, obj); \
311 } \
312  \
313 scope M0_UNUSED void name ## _be_list_add(struct m0_be_list *blist, \
314  struct m0_be_tx *tx, \
315  amb_type *obj) \
316 { \
317  m0_be_list_add(blist, &name ## _be_list_d, tx, obj); \
318 } \
319  \
320 scope M0_UNUSED void name ## _be_list_add_after(struct m0_be_list *blist, \
321  struct m0_be_tx *tx, \
322  amb_type *obj, \
323  amb_type *obj_new) \
324 { \
325  m0_be_list_add_after(blist, &name ## _be_list_d, tx, obj, obj_new); \
326 } \
327  \
328 scope M0_UNUSED void name ## _be_list_add_before(struct m0_be_list *blist, \
329  struct m0_be_tx *tx, \
330  amb_type *obj, \
331  amb_type *obj_new) \
332 { \
333  m0_be_list_add_before(blist, &name ## _be_list_d, tx, obj, obj_new); \
334 } \
335  \
336 scope M0_UNUSED void name ## _be_list_add_tail(struct m0_be_list *blist, \
337  struct m0_be_tx *tx, \
338  amb_type *obj) \
339 { \
340  m0_be_list_add_tail(blist, &name ## _be_list_d, tx, obj); \
341 } \
342  \
343 scope M0_UNUSED void name ## _be_list_del(struct m0_be_list *blist, \
344  struct m0_be_tx *tx, \
345  amb_type *obj) \
346 { \
347  m0_be_list_del(blist, &name ## _be_list_d, tx, obj); \
348 } \
349  \
350 struct __ ## name ## __be_list_terminate_me_with_a_semicolon { ; }
351 
352 
353 /* -------------------------------------------------------------------------
354  * List iteration macros.
355  * Refer to lib/tlist.h for detailed description and usecases.
356  * ------------------------------------------------------------------------- */
357 
358 #define m0_be_list_for(name, head, obj) \
359 do { \
360  const struct m0_be_list_descr *__descr = &name ## _be_list_d; \
361  void *__bl; \
362  struct m0_be_list *__head = (head); \
363  \
364  for (obj = m0_be_list_head(__head, __descr); \
365  obj != NULL && \
366  ((void)(__bl = m0_be_list_next(__head, __descr, obj)), true); \
367  obj = __bl)
368 
369 #define m0_be_list_endfor ;(void)__bl; } while (0)
370 
371 #define m0_be_list_forall(name, var, head, ...) \
372 ({ \
373  void *var; \
374  \
375  m0_be_list_for(name, head, var) { \
376  if (!({ __VA_ARGS__ ; })) \
377  break; \
378  } m0_be_list_endfor; \
379  var == NULL; \
380 })
381 
383 #endif /* __MOTR_BE_LIST_H__ */
384 
385 /*
386  * Local variables:
387  * c-indentation-style: "K&R"
388  * c-basic-offset: 8
389  * tab-width: 8
390  * fill-column: 80
391  * scroll-step: 1
392  * End:
393  */
394 /*
395  * vim: tabstop=8 shiftwidth=8 noexpandtab textwidth=80 nowrap
396  */
nr
static size_t nr
Definition: dump.c:1505
m0_be_list_op
m0_be_list_op
Definition: list.h:84
m0_be_list_tail
M0_INTERNAL void * m0_be_list_tail(struct m0_be_list *blist, const struct m0_be_list_descr *descr)
Definition: list.c:235
m0_be_list_del
M0_INTERNAL void m0_be_list_del(struct m0_be_list *blist, const struct m0_be_list_descr *descr, struct m0_be_tx *tx, void *obj)
Definition: list.c:488
m0_be_list_descr::bld_link_magic
uint64_t bld_link_magic
Definition: list.h:61
m0_be_list_head
M0_INTERNAL void * m0_be_list_head(struct m0_be_list *blist, const struct m0_be_list_descr *descr)
Definition: list.c:259
m0_be_list_descr::bld_head_magic
uint64_t bld_head_magic
Definition: list.h:62
m0_be_list_format_version
m0_be_list_format_version
Definition: list.h:46
m0_be_list_link
Definition: list.h:66
m0_be_list_descr::bld_name
const char * bld_name
Definition: list.h:58
m0_bcount_t
uint64_t m0_bcount_t
Definition: types.h:77
m0_be_list_create
M0_INTERNAL void m0_be_list_create(struct m0_be_list *blist, const struct m0_be_list_descr *descr, struct m0_be_tx *tx)
Definition: list.c:134
m0_be_list_add
M0_INTERNAL void m0_be_list_add(struct m0_be_list *blist, const struct m0_be_list_descr *descr, struct m0_be_tx *tx, void *obj)
Definition: list.c:326
M0_XCA_DOMAIN
enum m0_be_list_op M0_XCA_DOMAIN
m0_be_list_next
M0_INTERNAL void * m0_be_list_next(struct m0_be_list *blist, const struct m0_be_list_descr *descr, const void *obj)
Definition: list.c:300
m0_be_list_descr::bld_container_size
size_t bld_container_size
Definition: list.h:63
obj
static struct foo * obj
Definition: tlist.c:302
m0_format_footer
Definition: format.h:57
m0_be_list::bl_magic
uint64_t bl_magic
Definition: list.h:79
m0_be_list_add_tail
M0_INTERNAL void m0_be_list_add_tail(struct m0_be_list *blist, const struct m0_be_list_descr *descr, struct m0_be_tx *tx, void *obj)
Definition: list.c:451
M0_BE_LIST_FORMAT_VERSION
Definition: list.h:54
m0_be_tlink_create
M0_INTERNAL void m0_be_tlink_create(void *obj, const struct m0_be_list_descr *descr, struct m0_be_tx *tx)
Definition: list.c:185
M0_BLO_NR
Definition: list.h:94
M0_BLO_DESTROY
Definition: list.h:86
M0_BLO_DEL
Definition: list.h:91
m0_be_list_link::bll_prev
struct m0_be_list_link * bll_prev
Definition: list.h:68
m0_be_list_prev
M0_INTERNAL void * m0_be_list_prev(struct m0_be_list *blist, const struct m0_be_list_descr *descr, const void *obj)
Definition: list.c:278
m0_be_tx_credit
Definition: tx_credit.h:79
m0_be_list_add_before
M0_INTERNAL void m0_be_list_add_before(struct m0_be_list *blist, const struct m0_be_list_descr *descr, struct m0_be_tx *tx, void *obj, void *obj_new)
Definition: list.c:407
m0_be_tlink_destroy
M0_INTERNAL void m0_be_tlink_destroy(void *obj, const struct m0_be_list_descr *descr, struct m0_be_tx *tx)
Definition: list.c:200
m0_be_list_descr::bld_link_offset
int bld_link_offset
Definition: list.h:59
m0_be_list_add_after
M0_INTERNAL void m0_be_list_add_after(struct m0_be_list *blist, const struct m0_be_list_descr *descr, struct m0_be_tx *tx, void *obj, void *obj_new)
Definition: list.c:363
m0_be_list_head
Definition: list.h:71
M0_BLO_TLINK_CREATE
Definition: list.h:92
m0_be_list_head::blh_head
struct m0_be_list_link * blh_head
Definition: list.h:72
m0_be_list_is_empty
M0_INTERNAL bool m0_be_list_is_empty(struct m0_be_list *blist, const struct m0_be_list_descr *descr)
Definition: list.c:171
m0_be_list_descr
Definition: list.h:57
m0_be_list_descr::bld_link_magic_offset
int bld_link_magic_offset
Definition: list.h:60
M0_BLO_CREATE
Definition: list.h:85
M0_BE_LIST_FORMAT_VERSION_1
Definition: list.h:47
m0_be_list::bl_format_header
struct m0_format_header bl_format_header
Definition: list.h:77
m0_be_list::bl_format_footer
struct m0_format_footer bl_format_footer
Definition: list.h:80
M0_BLO_ADD
Definition: list.h:87
m0_be_list_head::blh_tail
struct m0_be_list_link * blh_tail
Definition: list.h:73
m0_be_list
Definition: list.h:76
m0_be_list::bl_head
struct m0_be_list_head bl_head
Definition: list.h:78
M0_BLO_TLINK_DESTROY
Definition: list.h:93
be
static struct m0_be_ut_backend be
Definition: service_ut.c:59
m0_be_list_credit
M0_INTERNAL void m0_be_list_credit(enum m0_be_list_op optype, m0_bcount_t nr, struct m0_be_tx_credit *accum)
Definition: list.c:56
m0_be_list_destroy
M0_INTERNAL void m0_be_list_destroy(struct m0_be_list *blist, const struct m0_be_list_descr *descr, struct m0_be_tx *tx)
Definition: list.c:156
m0_be_tx
Definition: tx.h:280
m0_format_header
Definition: format.h:38
m0_be_list_link::bll_next
struct m0_be_list_link * bll_next
Definition: list.h:67