libnl  3.2.13
cache.c
1 /*
2  * lib/cache.c Caching Module
3  *
4  * This library is free software; you can redistribute it and/or
5  * modify it under the terms of the GNU Lesser General Public
6  * License as published by the Free Software Foundation version 2.1
7  * of the License.
8  *
9  * Copyright (c) 2003-2008 Thomas Graf <tgraf@suug.ch>
10  */
11 
12 /**
13  * @ingroup cache_mngt
14  * @defgroup cache Cache
15  *
16  * @code
17  * Cache Management | | Type Specific Cache Operations
18  *
19  * | | +----------------+ +------------+
20  * | request update | | msg_parser |
21  * | | +----------------+ +------------+
22  * +- - - - -^- - - - - - - -^- -|- - - -
23  * nl_cache_update: | | | |
24  * 1) --------- co_request_update ------+ | |
25  * | | |
26  * 2) destroy old cache +----------- pp_cb ---------|---+
27  * | | |
28  * 3) ---------- nl_recvmsgs ----------+ +- cb_valid -+
29  * +--------------+ | | | |
30  * | nl_cache_add |<-----+ + - - -v- -|- - - - - - - - - - -
31  * +--------------+ | | +-------------+
32  * | nl_recvmsgs |
33  * | | +-----|-^-----+
34  * +---v-|---+
35  * | | | nl_recv |
36  * +---------+
37  * | | Core Netlink
38  * @endcode
39  *
40  * Related sections in the development guide:
41  * - @core_doc{core_cache, Caching System}
42  *
43  * @{
44  *
45  * Header
46  * ------
47  * ~~~~{.c}
48  * #include <netlink/cache.h>
49  * ~~~~
50  */
51 
52 #include <netlink-local.h>
53 #include <netlink/netlink.h>
54 #include <netlink/cache.h>
55 #include <netlink/object.h>
56 #include <netlink/utils.h>
57 
58 /**
59  * @name Access Functions
60  * @{
61  */
62 
63 /**
64  * Return the number of items in the cache
65  * @arg cache cache handle
66  */
67 int nl_cache_nitems(struct nl_cache *cache)
68 {
69  return cache->c_nitems;
70 }
71 
72 /**
73  * Return the number of items matching a filter in the cache
74  * @arg cache Cache object.
75  * @arg filter Filter object.
76  */
77 int nl_cache_nitems_filter(struct nl_cache *cache, struct nl_object *filter)
78 {
79  struct nl_object *obj;
80  int nitems = 0;
81 
82  if (cache->c_ops == NULL)
83  BUG();
84 
85  nl_list_for_each_entry(obj, &cache->c_items, ce_list) {
86  if (filter && !nl_object_match_filter(obj, filter))
87  continue;
88 
89  nitems++;
90  }
91 
92  return nitems;
93 }
94 
95 /**
96  * Returns \b true if the cache is empty.
97  * @arg cache Cache to check
98  * @return \a true if the cache is empty, otherwise \b false is returned.
99  */
100 int nl_cache_is_empty(struct nl_cache *cache)
101 {
102  return nl_list_empty(&cache->c_items);
103 }
104 
105 /**
106  * Return the operations set of the cache
107  * @arg cache cache handle
108  */
109 struct nl_cache_ops *nl_cache_get_ops(struct nl_cache *cache)
110 {
111  return cache->c_ops;
112 }
113 
114 /**
115  * Return the first element in the cache
116  * @arg cache cache handle
117  */
118 struct nl_object *nl_cache_get_first(struct nl_cache *cache)
119 {
120  if (nl_list_empty(&cache->c_items))
121  return NULL;
122 
123  return nl_list_entry(cache->c_items.next,
124  struct nl_object, ce_list);
125 }
126 
127 /**
128  * Return the last element in the cache
129  * @arg cache cache handle
130  */
131 struct nl_object *nl_cache_get_last(struct nl_cache *cache)
132 {
133  if (nl_list_empty(&cache->c_items))
134  return NULL;
135 
136  return nl_list_entry(cache->c_items.prev,
137  struct nl_object, ce_list);
138 }
139 
140 /**
141  * Return the next element in the cache
142  * @arg obj current object
143  */
145 {
146  if (nl_list_at_tail(obj, &obj->ce_cache->c_items, ce_list))
147  return NULL;
148  else
149  return nl_list_entry(obj->ce_list.next,
150  struct nl_object, ce_list);
151 }
152 
153 /**
154  * Return the previous element in the cache
155  * @arg obj current object
156  */
158 {
159  if (nl_list_at_head(obj, &obj->ce_cache->c_items, ce_list))
160  return NULL;
161  else
162  return nl_list_entry(obj->ce_list.prev,
163  struct nl_object, ce_list);
164 }
165 
166 /** @} */
167 
168 /**
169  * @name Cache Allocation/Deletion
170  * @{
171  */
172 
173 /**
174  * Allocate new cache
175  * @arg ops Cache operations
176  *
177  * Allocate and initialize a new cache based on the cache operations
178  * provided.
179  *
180  * @return Allocated cache or NULL if allocation failed.
181  */
182 struct nl_cache *nl_cache_alloc(struct nl_cache_ops *ops)
183 {
184  struct nl_cache *cache;
185 
186  cache = calloc(1, sizeof(*cache));
187  if (!cache)
188  return NULL;
189 
190  nl_init_list_head(&cache->c_items);
191  cache->c_ops = ops;
192 
193  NL_DBG(2, "Allocated cache %p <%s>.\n", cache, nl_cache_name(cache));
194 
195  return cache;
196 }
197 
198 /**
199  * Allocate new cache and fill it
200  * @arg ops Cache operations
201  * @arg sock Netlink socket
202  * @arg result Result pointer
203  *
204  * Allocate new cache and fill it. Equivalent to calling:
205  * @code
206  * cache = nl_cache_alloc(ops);
207  * nl_cache_refill(sock, cache);
208  * @endcode
209  *
210  * @see nl_cache_alloc
211  *
212  * @return 0 on success or a negative error code.
213  */
214 int nl_cache_alloc_and_fill(struct nl_cache_ops *ops, struct nl_sock *sock,
215  struct nl_cache **result)
216 {
217  struct nl_cache *cache;
218  int err;
219 
220  if (!(cache = nl_cache_alloc(ops)))
221  return -NLE_NOMEM;
222 
223  if (sock && (err = nl_cache_refill(sock, cache)) < 0) {
224  nl_cache_free(cache);
225  return err;
226  }
227 
228  *result = cache;
229  return 0;
230 }
231 
232 /**
233  * Allocate new cache based on type name
234  * @arg kind Name of cache type
235  * @arg result Result pointer
236  *
237  * Lookup cache ops via nl_cache_ops_lookup() and allocate the cache
238  * by calling nl_cache_alloc(). Stores the allocated cache in the
239  * result pointer provided.
240  *
241  * @see nl_cache_alloc
242  *
243  * @return 0 on success or a negative error code.
244  */
245 int nl_cache_alloc_name(const char *kind, struct nl_cache **result)
246 {
247  struct nl_cache_ops *ops;
248  struct nl_cache *cache;
249 
250  ops = nl_cache_ops_lookup(kind);
251  if (!ops)
252  return -NLE_NOCACHE;
253 
254  if (!(cache = nl_cache_alloc(ops)))
255  return -NLE_NOMEM;
256 
257  *result = cache;
258  return 0;
259 }
260 
261 /**
262  * Allocate new cache containing a subset of an existing cache
263  * @arg orig Original cache to base new cache on
264  * @arg filter Filter defining the subset to be filled into the new cache
265  *
266  * Allocates a new cache matching the type of the cache specified by
267  * \p orig. Iterates over the \p orig cache applying the specified
268  * \p filter and copies all objects that match to the new cache.
269  *
270  * The copied objects are clones but do not contain a reference to each
271  * other. Later modifications to objects in the original cache will
272  * not affect objects in the new cache.
273  *
274  * @return A newly allocated cache or NULL.
275  */
276 struct nl_cache *nl_cache_subset(struct nl_cache *orig,
277  struct nl_object *filter)
278 {
279  struct nl_cache *cache;
280  struct nl_object *obj;
281 
282  if (!filter)
283  BUG();
284 
285  cache = nl_cache_alloc(orig->c_ops);
286  if (!cache)
287  return NULL;
288 
289  nl_list_for_each_entry(obj, &orig->c_items, ce_list) {
290  if (!nl_object_match_filter(obj, filter))
291  continue;
292 
293  nl_cache_add(cache, obj);
294  }
295 
296  return cache;
297 }
298 
299 /**
300  * Allocate new cache and copy the contents of an existing cache
301  * @arg cache Original cache to base new cache on
302  *
303  * Allocates a new cache matching the type of the cache specified by
304  * \p cache. Iterates over the \p cache cache and copies all objects
305  * to the new cache.
306  *
307  * The copied objects are clones but do not contain a reference to each
308  * other. Later modifications to objects in the original cache will
309  * not affect objects in the new cache.
310  *
311  * @return A newly allocated cache or NULL.
312  */
313 struct nl_cache *nl_cache_clone(struct nl_cache *cache)
314 {
315  struct nl_cache_ops *ops = nl_cache_get_ops(cache);
316  struct nl_cache *clone;
317  struct nl_object *obj;
318 
319  clone = nl_cache_alloc(ops);
320  if (!clone)
321  return NULL;
322 
323  nl_list_for_each_entry(obj, &cache->c_items, ce_list)
324  nl_cache_add(clone, obj);
325 
326  return clone;
327 }
328 
329 /**
330  * Remove all objects of a cache.
331  * @arg cache Cache to clear
332  *
333  * The objects are unliked/removed from the cache by calling
334  * nl_cache_remove() on each object in the cache. If any of the objects
335  * to not contain any further references to them, those objects will
336  * be freed.
337  *
338  * Unlike with nl_cache_free(), the cache is not freed just emptied.
339  */
340 void nl_cache_clear(struct nl_cache *cache)
341 {
342  struct nl_object *obj, *tmp;
343 
344  NL_DBG(1, "Clearing cache %p <%s>...\n", cache, nl_cache_name(cache));
345 
346  nl_list_for_each_entry_safe(obj, tmp, &cache->c_items, ce_list)
347  nl_cache_remove(obj);
348 }
349 
350 /**
351  * Free a cache.
352  * @arg cache Cache to free.
353  *
354  * Calls nl_cache_clear() to remove all objects associated with the
355  * cache and frees the cache afterwards.
356  *
357  * @see nl_cache_clear()
358  */
359 void nl_cache_free(struct nl_cache *cache)
360 {
361  if (!cache)
362  return;
363 
364  nl_cache_clear(cache);
365  NL_DBG(1, "Freeing cache %p <%s>...\n", cache, nl_cache_name(cache));
366  free(cache);
367 }
368 
369 /** @} */
370 
371 /**
372  * @name Cache Modifications
373  * @{
374  */
375 
376 static int __cache_add(struct nl_cache *cache, struct nl_object *obj)
377 {
378  obj->ce_cache = cache;
379 
380  nl_list_add_tail(&obj->ce_list, &cache->c_items);
381  cache->c_nitems++;
382 
383  NL_DBG(1, "Added %p to cache %p <%s>.\n",
384  obj, cache, nl_cache_name(cache));
385 
386  return 0;
387 }
388 
389 /**
390  * Add object to cache.
391  * @arg cache Cache
392  * @arg obj Object to be added to the cache
393  *
394  * Adds the object \p obj to the specified \p cache. In case the object
395  * is already associated with another cache, the object is cloned before
396  * adding it to the cache. In this case, the sole reference to the object
397  * will be the one of the cache. Therefore clearing/freeing the cache
398  * will result in the object being freed again.
399  *
400  * If the object has not been associated with a cache yet, the reference
401  * counter of the object is incremented to account for the additional
402  * reference.
403  *
404  * The type of the object and cache must match, otherwise an error is
405  * returned (-NLE_OBJ_MISMATCH).
406  *
407  * @see nl_cache_move()
408  *
409  * @return 0 or a negative error code.
410  */
411 int nl_cache_add(struct nl_cache *cache, struct nl_object *obj)
412 {
413  struct nl_object *new;
414 
415  if (cache->c_ops->co_obj_ops != obj->ce_ops)
416  return -NLE_OBJ_MISMATCH;
417 
418  if (!nl_list_empty(&obj->ce_list)) {
419  new = nl_object_clone(obj);
420  if (!new)
421  return -NLE_NOMEM;
422  } else {
423  nl_object_get(obj);
424  new = obj;
425  }
426 
427  return __cache_add(cache, new);
428 }
429 
430 /**
431  * Move object from one cache to another
432  * @arg cache Cache to move object to.
433  * @arg obj Object subject to be moved
434  *
435  * Removes the the specified object \p obj from its associated cache
436  * and moves it to another cache.
437  *
438  * If the object is not associated with a cache, the function behaves
439  * just like nl_cache_add().
440  *
441  * The type of the object and cache must match, otherwise an error is
442  * returned (-NLE_OBJ_MISMATCH).
443  *
444  * @see nl_cache_add()
445  *
446  * @return 0 on success or a negative error code.
447  */
448 int nl_cache_move(struct nl_cache *cache, struct nl_object *obj)
449 {
450  if (cache->c_ops->co_obj_ops != obj->ce_ops)
451  return -NLE_OBJ_MISMATCH;
452 
453  NL_DBG(3, "Moving object %p to cache %p\n", obj, cache);
454 
455  /* Acquire reference, if already in a cache this will be
456  * reverted during removal */
457  nl_object_get(obj);
458 
459  if (!nl_list_empty(&obj->ce_list))
460  nl_cache_remove(obj);
461 
462  return __cache_add(cache, obj);
463 }
464 
465 /**
466  * Remove object from cache.
467  * @arg obj Object to remove from cache
468  *
469  * Removes the object \c obj from the cache it is associated with. The
470  * reference counter of the object will be decremented. If the reference
471  * to the object was the only one remaining, the object will be freed.
472  *
473  * If no cache is associated with the object, this function is a NOP.
474  */
475 void nl_cache_remove(struct nl_object *obj)
476 {
477  struct nl_cache *cache = obj->ce_cache;
478 
479  if (cache == NULL)
480  return;
481 
482  nl_list_del(&obj->ce_list);
483  obj->ce_cache = NULL;
484  nl_object_put(obj);
485  cache->c_nitems--;
486 
487  NL_DBG(1, "Deleted %p from cache %p <%s>.\n",
488  obj, cache, nl_cache_name(cache));
489 }
490 
491 /** @} */
492 
493 /**
494  * @name Synchronization
495  * @{
496  */
497 
498 /**
499  * Set synchronization arg1 of cache
500  * @arg cache Cache
501  * @arg arg argument
502  *
503  * Synchronization arguments are used to specify filters when
504  * requesting dumps from the kernel.
505  */
506 void nl_cache_set_arg1(struct nl_cache *cache, int arg)
507 {
508  cache->c_iarg1 = arg;
509 }
510 
511 /**
512  * Set synchronization arg2 of cache
513  * @arg cache Cache
514  * @arg arg argument
515  *
516  * Synchronization arguments are used to specify filters when
517  * requesting dumps from the kernel.
518  */
519 void nl_cache_set_arg2(struct nl_cache *cache, int arg)
520 {
521  cache->c_iarg2 = arg;
522 }
523 
524 /**
525  * Invoke the request-update operation
526  * @arg sk Netlink socket.
527  * @arg cache Cache
528  *
529  * This function causes the \e request-update function of the cache
530  * operations to be invoked. This usually causes a dump request to
531  * be sent over the netlink socket which triggers the kernel to dump
532  * all objects of a specific type to be dumped onto the netlink
533  * socket for pickup.
534  *
535  * The behaviour of this function depends on the implemenation of
536  * the \e request_update function of each individual type of cache.
537  *
538  * This function will not have any effects on the cache (unless the
539  * request_update implementation of the cache operations does so).
540  *
541  * Use nl_cache_pickup() to pick-up (read) the objects from the socket
542  * and fill them into the cache.
543  *
544  * @see nl_cache_pickup(), nl_cache_resync()
545  *
546  * @return 0 on success or a negative error code.
547  */
548 static int nl_cache_request_full_dump(struct nl_sock *sk,
549  struct nl_cache *cache)
550 {
551  NL_DBG(2, "Requesting dump from kernel for cache %p <%s>...\n",
552  cache, nl_cache_name(cache));
553 
554  if (cache->c_ops->co_request_update == NULL)
555  return -NLE_OPNOTSUPP;
556 
557  return cache->c_ops->co_request_update(cache, sk);
558 }
559 
560 /** @cond SKIP */
561 struct update_xdata {
562  struct nl_cache_ops *ops;
563  struct nl_parser_param *params;
564 };
565 
566 static int update_msg_parser(struct nl_msg *msg, void *arg)
567 {
568  struct update_xdata *x = arg;
569 
570  return nl_cache_parse(x->ops, &msg->nm_src, msg->nm_nlh, x->params);
571 }
572 /** @endcond */
573 
574 /**
575  * Pick-up a netlink request-update with your own parser
576  * @arg sk Netlink socket
577  * @arg cache Cache
578  * @arg param Parser parameters
579  */
580 static int __cache_pickup(struct nl_sock *sk, struct nl_cache *cache,
581  struct nl_parser_param *param)
582 {
583  int err;
584  struct nl_cb *cb;
585  struct update_xdata x = {
586  .ops = cache->c_ops,
587  .params = param,
588  };
589 
590  NL_DBG(1, "Picking up answer for cache %p <%s>...\n",
591  cache, nl_cache_name(cache));
592 
593  cb = nl_cb_clone(sk->s_cb);
594  if (cb == NULL)
595  return -NLE_NOMEM;
596 
597  nl_cb_set(cb, NL_CB_VALID, NL_CB_CUSTOM, update_msg_parser, &x);
598 
599  err = nl_recvmsgs(sk, cb);
600  if (err < 0)
601  NL_DBG(2, "While picking up for %p <%s>, recvmsgs() returned " \
602  "%d: %s", cache, nl_cache_name(cache),
603  err, nl_geterror(err));
604 
605  nl_cb_put(cb);
606 
607  return err;
608 }
609 
610 static int pickup_cb(struct nl_object *c, struct nl_parser_param *p)
611 {
612  return nl_cache_add((struct nl_cache *) p->pp_arg, c);
613 }
614 
615 /**
616  * Pickup a netlink dump response and put it into a cache.
617  * @arg sk Netlink socket.
618  * @arg cache Cache to put items into.
619  *
620  * Waits for netlink messages to arrive, parses them and puts them into
621  * the specified cache.
622  *
623  * @return 0 on success or a negative error code.
624  */
625 int nl_cache_pickup(struct nl_sock *sk, struct nl_cache *cache)
626 {
627  struct nl_parser_param p = {
628  .pp_cb = pickup_cb,
629  .pp_arg = cache,
630  };
631 
632  return __cache_pickup(sk, cache, &p);
633 }
634 
635 static int cache_include(struct nl_cache *cache, struct nl_object *obj,
636  struct nl_msgtype *type, change_func_t cb, void *data)
637 {
638  struct nl_object *old;
639 
640  switch (type->mt_act) {
641  case NL_ACT_NEW:
642  case NL_ACT_DEL:
643  old = nl_cache_search(cache, obj);
644  if (old) {
645  nl_cache_remove(old);
646  if (type->mt_act == NL_ACT_DEL) {
647  if (cb)
648  cb(cache, old, NL_ACT_DEL, data);
649  nl_object_put(old);
650  }
651  }
652 
653  if (type->mt_act == NL_ACT_NEW) {
654  nl_cache_move(cache, obj);
655  if (old == NULL && cb)
656  cb(cache, obj, NL_ACT_NEW, data);
657  else if (old) {
658  if (nl_object_diff(old, obj) && cb)
659  cb(cache, obj, NL_ACT_CHANGE, data);
660 
661  nl_object_put(old);
662  }
663  }
664  break;
665  default:
666  NL_DBG(2, "Unknown action associated to object %p\n", obj);
667  return 0;
668  }
669 
670  return 0;
671 }
672 
673 int nl_cache_include(struct nl_cache *cache, struct nl_object *obj,
674  change_func_t change_cb, void *data)
675 {
676  struct nl_cache_ops *ops = cache->c_ops;
677  int i;
678 
679  if (ops->co_obj_ops != obj->ce_ops)
680  return -NLE_OBJ_MISMATCH;
681 
682  for (i = 0; ops->co_msgtypes[i].mt_id >= 0; i++)
683  if (ops->co_msgtypes[i].mt_id == obj->ce_msgtype)
684  return cache_include(cache, obj, &ops->co_msgtypes[i],
685  change_cb, data);
686 
687  return -NLE_MSGTYPE_NOSUPPORT;
688 }
689 
690 static int resync_cb(struct nl_object *c, struct nl_parser_param *p)
691 {
692  struct nl_cache_assoc *ca = p->pp_arg;
693 
694  return nl_cache_include(ca->ca_cache, c, ca->ca_change, ca->ca_change_data);
695 }
696 
697 int nl_cache_resync(struct nl_sock *sk, struct nl_cache *cache,
698  change_func_t change_cb, void *data)
699 {
700  struct nl_object *obj, *next;
701  struct nl_cache_assoc ca = {
702  .ca_cache = cache,
703  .ca_change = change_cb,
704  .ca_change_data = data,
705  };
706  struct nl_parser_param p = {
707  .pp_cb = resync_cb,
708  .pp_arg = &ca,
709  };
710  int err;
711 
712  NL_DBG(1, "Resyncing cache %p <%s>...\n", cache, nl_cache_name(cache));
713 
714 restart:
715  /* Mark all objects so we can see if some of them are obsolete */
716  nl_cache_mark_all(cache);
717 
718  err = nl_cache_request_full_dump(sk, cache);
719  if (err < 0)
720  goto errout;
721 
722  err = __cache_pickup(sk, cache, &p);
723  if (err == -NLE_DUMP_INTR)
724  goto restart;
725  else if (err < 0)
726  goto errout;
727 
728  nl_list_for_each_entry_safe(obj, next, &cache->c_items, ce_list) {
729  if (nl_object_is_marked(obj)) {
730  nl_object_get(obj);
731  nl_cache_remove(obj);
732  if (change_cb)
733  change_cb(cache, obj, NL_ACT_DEL, data);
734  nl_object_put(obj);
735  }
736  }
737 
738  NL_DBG(1, "Finished resyncing %p <%s>\n", cache, nl_cache_name(cache));
739 
740  err = 0;
741 errout:
742  return err;
743 }
744 
745 /** @} */
746 
747 /**
748  * @name Parsing
749  * @{
750  */
751 
752 /** @cond SKIP */
753 int nl_cache_parse(struct nl_cache_ops *ops, struct sockaddr_nl *who,
754  struct nlmsghdr *nlh, struct nl_parser_param *params)
755 {
756  int i, err;
757 
758  if (!nlmsg_valid_hdr(nlh, ops->co_hdrsize))
759  return -NLE_MSG_TOOSHORT;
760 
761  for (i = 0; ops->co_msgtypes[i].mt_id >= 0; i++) {
762  if (ops->co_msgtypes[i].mt_id == nlh->nlmsg_type) {
763  err = ops->co_msg_parser(ops, who, nlh, params);
764  if (err != -NLE_OPNOTSUPP)
765  goto errout;
766  }
767  }
768 
769 
770  err = -NLE_MSGTYPE_NOSUPPORT;
771 errout:
772  return err;
773 }
774 /** @endcond */
775 
776 /**
777  * Parse a netlink message and add it to the cache.
778  * @arg cache cache to add element to
779  * @arg msg netlink message
780  *
781  * Parses a netlink message by calling the cache specific message parser
782  * and adds the new element to the cache.
783  *
784  * @return 0 or a negative error code.
785  */
786 int nl_cache_parse_and_add(struct nl_cache *cache, struct nl_msg *msg)
787 {
788  struct nl_parser_param p = {
789  .pp_cb = pickup_cb,
790  .pp_arg = cache,
791  };
792 
793  return nl_cache_parse(cache->c_ops, NULL, nlmsg_hdr(msg), &p);
794 }
795 
796 /**
797  * (Re)fill a cache with the contents in the kernel.
798  * @arg sk Netlink socket.
799  * @arg cache cache to update
800  *
801  * Clears the specified cache and fills it with the current state in
802  * the kernel.
803  *
804  * @return 0 or a negative error code.
805  */
806 int nl_cache_refill(struct nl_sock *sk, struct nl_cache *cache)
807 {
808  int err;
809 
810 restart:
811  err = nl_cache_request_full_dump(sk, cache);
812  if (err < 0)
813  return err;
814 
815  NL_DBG(2, "Upading cache %p <%s>, request sent, waiting for dump...\n",
816  cache, nl_cache_name(cache));
817  nl_cache_clear(cache);
818 
819  err = nl_cache_pickup(sk, cache);
820  if (err == -NLE_DUMP_INTR) {
821  fprintf(stderr, "dump interrupted, restarting!\n");
822  goto restart;
823  }
824 
825  return err;
826 }
827 
828 /** @} */
829 
830 /**
831  * @name Utillities
832  * @{
833  */
834 
835 /**
836  * Search object in cache
837  * @arg cache Cache
838  * @arg needle Object to look for.
839  *
840  * Searches the cache for an object which matches the object \p needle.
841  * The function nl_object_identical() is used to determine if the
842  * objects match. If a matching object is found, the reference counter
843  * is incremented and the object is returned.
844  *
845  * Therefore, if an object is returned, the reference to the object
846  * must be returned by calling nl_object_put() after usage.
847  *
848  * @return Reference to object or NULL if not found.
849  */
850 struct nl_object *nl_cache_search(struct nl_cache *cache,
851  struct nl_object *needle)
852 {
853  struct nl_object *obj;
854 
855  nl_list_for_each_entry(obj, &cache->c_items, ce_list) {
856  if (nl_object_identical(obj, needle)) {
857  nl_object_get(obj);
858  return obj;
859  }
860  }
861 
862  return NULL;
863 }
864 
865 /**
866  * Mark all objects of a cache
867  * @arg cache Cache
868  *
869  * Marks all objects of a cache by calling nl_object_mark() on each
870  * object associated with the cache.
871  */
872 void nl_cache_mark_all(struct nl_cache *cache)
873 {
874  struct nl_object *obj;
875 
876  NL_DBG(2, "Marking all objects in cache %p <%s>...\n",
877  cache, nl_cache_name(cache));
878 
879  nl_list_for_each_entry(obj, &cache->c_items, ce_list)
880  nl_object_mark(obj);
881 }
882 
883 /** @} */
884 
885 /**
886  * @name Dumping
887  * @{
888  */
889 
890 /**
891  * Dump all elements of a cache.
892  * @arg cache cache to dump
893  * @arg params dumping parameters
894  *
895  * Dumps all elements of the \a cache to the file descriptor \a fd.
896  */
897 void nl_cache_dump(struct nl_cache *cache, struct nl_dump_params *params)
898 {
899  nl_cache_dump_filter(cache, params, NULL);
900 }
901 
902 /**
903  * Dump all elements of a cache (filtered).
904  * @arg cache cache to dump
905  * @arg params dumping parameters (optional)
906  * @arg filter filter object
907  *
908  * Dumps all elements of the \a cache to the file descriptor \a fd
909  * given they match the given filter \a filter.
910  */
911 void nl_cache_dump_filter(struct nl_cache *cache,
912  struct nl_dump_params *params,
913  struct nl_object *filter)
914 {
915  int type = params ? params->dp_type : NL_DUMP_DETAILS;
916  struct nl_object_ops *ops;
917  struct nl_object *obj;
918 
919  NL_DBG(2, "Dumping cache %p <%s> filter %p\n",
920  cache, nl_cache_name(cache), filter);
921 
922  if (type > NL_DUMP_MAX || type < 0)
923  BUG();
924 
925  if (cache->c_ops == NULL)
926  BUG();
927 
928  ops = cache->c_ops->co_obj_ops;
929  if (!ops->oo_dump[type])
930  return;
931 
932  if (params->dp_buf)
933  memset(params->dp_buf, 0, params->dp_buflen);
934 
935  nl_list_for_each_entry(obj, &cache->c_items, ce_list) {
936  if (filter && !nl_object_match_filter(obj, filter))
937  continue;
938 
939  NL_DBG(4, "Dumping object %p...\n", obj);
940  dump_from_ops(obj, params);
941  }
942 }
943 
944 /** @} */
945 
946 /**
947  * @name Iterators
948  * @{
949  */
950 
951 /**
952  * Call a callback on each element of the cache.
953  * @arg cache cache to iterate on
954  * @arg cb callback function
955  * @arg arg argument passed to callback function
956  *
957  * Calls a callback function \a cb on each element of the \a cache.
958  * The argument \a arg is passed on the callback function.
959  */
960 void nl_cache_foreach(struct nl_cache *cache,
961  void (*cb)(struct nl_object *, void *), void *arg)
962 {
963  nl_cache_foreach_filter(cache, NULL, cb, arg);
964 }
965 
966 /**
967  * Call a callback on each element of the cache (filtered).
968  * @arg cache cache to iterate on
969  * @arg filter filter object
970  * @arg cb callback function
971  * @arg arg argument passed to callback function
972  *
973  * Calls a callback function \a cb on each element of the \a cache
974  * that matches the \a filter. The argument \a arg is passed on
975  * to the callback function.
976  */
977 void nl_cache_foreach_filter(struct nl_cache *cache, struct nl_object *filter,
978  void (*cb)(struct nl_object *, void *), void *arg)
979 {
980  struct nl_object *obj, *tmp;
981 
982  if (cache->c_ops == NULL)
983  BUG();
984 
985  nl_list_for_each_entry_safe(obj, tmp, &cache->c_items, ce_list) {
986  if (filter) {
987  int diff = nl_object_match_filter(obj, filter);
988 
989  NL_DBG(3, "%p<->%p object difference: %x\n",
990  obj, filter, diff);
991 
992  if (!diff)
993  continue;
994  }
995 
996  /* Caller may hold obj for a long time */
997  nl_object_get(obj);
998 
999  cb(obj, arg);
1000 
1001  nl_object_put(obj);
1002  }
1003 }
1004 
1005 /** @} */
1006 
1007 /** @} */