Cache
[Caching]

Modules

 Object
 Cache Implementation

Access Functions



int nl_cache_nitems (struct nl_cache *cache)
 Return the number of items in the cache.
int nl_cache_nitems_filter (struct nl_cache *cache, struct nl_object *filter)
 Return the number of items matching a filter in the cache.
int nl_cache_is_empty (struct nl_cache *cache)
 Returns true if the cache is empty.
struct nl_cache_opsnl_cache_get_ops (struct nl_cache *cache)
 Return the operations set of the cache.
struct nl_object * nl_cache_get_first (struct nl_cache *cache)
 Return the first element in the cache.
struct nl_object * nl_cache_get_last (struct nl_cache *cache)
 Return the last element in the cache.
struct nl_object * nl_cache_get_next (struct nl_object *obj)
 Return the next element in the cache.
struct nl_object * nl_cache_get_prev (struct nl_object *obj)
 Return the previous element in the cache.

Cache Creation/Deletion



struct nl_cache * nl_cache_alloc (struct nl_cache_ops *ops)
 Allocate an empty cache.
struct nl_cache * nl_cache_alloc_name (const char *kind)
 Allocate an empty cache based on type name.
struct nl_cache * nl_cache_subset (struct nl_cache *orig, struct nl_object *filter)
 Allocate a new cache containing a subset of a cache.
void nl_cache_clear (struct nl_cache *cache)
 Clear a cache.
void nl_cache_free (struct nl_cache *cache)
 Free a cache.

Cache Modifications



int nl_cache_add (struct nl_cache *cache, struct nl_object *obj)
 Add object to a cache.
int nl_cache_move (struct nl_cache *cache, struct nl_object *obj)
 Move object from one cache to another.
void nl_cache_remove (struct nl_object *obj)
 Removes an object from a cache.
struct nl_object * nl_cache_search (struct nl_cache *cache, struct nl_object *needle)
 Search for an object in a cache.

Synchronization



int nl_cache_request_full_dump (struct nl_handle *handle, struct nl_cache *cache)
 Request a full dump from the kernel to fill a cache.
int __cache_pickup (struct nl_handle *handle, struct nl_cache *cache, struct nl_parser_param *param)
int nl_cache_pickup (struct nl_handle *handle, struct nl_cache *cache)
 Pickup a netlink dump response and put it into a cache.
int nl_cache_include (struct nl_cache *cache, struct nl_object *obj, change_func_t change_cb)
int nl_cache_resync (struct nl_handle *handle, struct nl_cache *cache, change_func_t change_cb)

Parsing



int nl_cache_parse_and_add (struct nl_cache *cache, struct nl_msg *msg)
 Parse a netlink message and add it to the cache.
int nl_cache_refill (struct nl_handle *handle, struct nl_cache *cache)
 (Re)fill a cache with the contents in the kernel.

Utillities



void nl_cache_mark_all (struct nl_cache *cache)
 Mark all objects in a cache.

Dumping



void nl_cache_dump (struct nl_cache *cache, struct nl_dump_params *params)
 Dump all elements of a cache.
void nl_cache_dump_filter (struct nl_cache *cache, struct nl_dump_params *params, struct nl_object *filter)
 Dump all elements of a cache (filtered).

Iterators



void nl_cache_foreach (struct nl_cache *cache, void(*cb)(struct nl_object *, void *), void *arg)
 Call a callback on each element of the cache.
void nl_cache_foreach_filter (struct nl_cache *cache, struct nl_object *filter, void(*cb)(struct nl_object *, void *), void *arg)
 Call a callback on each element of the cache (filtered).

Detailed Description

   Cache Management             |    | Type Specific Cache Operations
                                      
                                |    | +----------------+ +------------+
                                       | request update | | msg_parser |
                                |    | +----------------+ +------------+
                                     +- - - - -^- - - - - - - -^- -|- - - -
    nl_cache_update:            |              |               |   |
          1) --------- co_request_update ------+               |   |
                                |                              |   |
          2) destroy old cache     +----------- pp_cb ---------|---+
                                |  |                           |
          3) ---------- nl_recvmsgs ----------+   +- cb_valid -+
             +--------------+   |  |          |   |
             | nl_cache_add |<-----+   + - - -v- -|- - - - - - - - - - -
             +--------------+   |      | +-------------+
                                         | nl_recvmsgs |
                                |      | +-----|-^-----+
                                           +---v-|---+
                                |      |   | nl_recv |
                                           +---------+
                                |      |                 Core Netlink

Function Documentation

int nl_cache_nitems ( struct nl_cache *  cache  ) 
Parameters:
cache cache handle

Definition at line 58 of file cache.c.

00059 {
00060         return cache->c_nitems;
00061 }

int nl_cache_nitems_filter ( struct nl_cache *  cache,
struct nl_object *  filter 
)
Parameters:
cache Cache object.
filter Filter object.

Definition at line 68 of file cache.c.

References nl_object_match_filter().

00069 {
00070         struct nl_object_ops *ops;
00071         struct nl_object *obj;
00072         int nitems = 0;
00073 
00074         if (cache->c_ops == NULL)
00075                 BUG();
00076 
00077         ops = cache->c_ops->co_obj_ops;
00078         
00079         nl_list_for_each_entry(obj, &cache->c_items, ce_list) {
00080                 if (filter && !nl_object_match_filter(obj, filter))
00081                         continue;
00082 
00083                 nitems++;
00084         }
00085 
00086         return nitems;
00087 }

int nl_cache_is_empty ( struct nl_cache *  cache  ) 
Parameters:
cache Cache to check
Returns:
true if the cache is empty, otherwise false is returned.

Definition at line 94 of file cache.c.

00095 {
00096         return nl_list_empty(&cache->c_items);
00097 }

struct nl_cache_ops* nl_cache_get_ops ( struct nl_cache *  cache  )  [read]
Parameters:
cache cache handle

Definition at line 103 of file cache.c.

00104 {
00105         return cache->c_ops;
00106 }

struct nl_object* nl_cache_get_first ( struct nl_cache *  cache  )  [read]
Parameters:
cache cache handle

Definition at line 112 of file cache.c.

00113 {
00114         if (nl_list_empty(&cache->c_items))
00115                 return NULL;
00116 
00117         return nl_list_entry(cache->c_items.next,
00118                              struct nl_object, ce_list);
00119 }

struct nl_object* nl_cache_get_last ( struct nl_cache *  cache  )  [read]
Parameters:
cache cache handle

Definition at line 125 of file cache.c.

00126 {
00127         if (nl_list_empty(&cache->c_items))
00128                 return NULL;
00129 
00130         return nl_list_entry(cache->c_items.prev,
00131                              struct nl_object, ce_list);
00132 }

struct nl_object* nl_cache_get_next ( struct nl_object *  obj  )  [read]
Parameters:
obj current object

Definition at line 138 of file cache.c.

00139 {
00140         if (nl_list_at_tail(obj, &obj->ce_cache->c_items, ce_list))
00141                 return NULL;
00142         else
00143                 return nl_list_entry(obj->ce_list.next,
00144                                      struct nl_object, ce_list);
00145 }

struct nl_object* nl_cache_get_prev ( struct nl_object *  obj  )  [read]
Parameters:
obj current object

Definition at line 151 of file cache.c.

00152 {
00153         if (nl_list_at_head(obj, &obj->ce_cache->c_items, ce_list))
00154                 return NULL;
00155         else
00156                 return nl_list_entry(obj->ce_list.prev,
00157                                      struct nl_object, ce_list);
00158 }

struct nl_cache* nl_cache_alloc ( struct nl_cache_ops ops  )  [read]
Parameters:
ops cache operations to base the cache on
Returns:
A newly allocated and initialized cache.

Definition at line 173 of file cache.c.

Referenced by flnl_result_alloc_cache(), nfnl_ct_alloc_cache(), nl_cache_alloc_name(), nl_cache_mngr_add(), nl_cache_subset(), rtnl_class_alloc_cache(), rtnl_cls_alloc_cache(), rtnl_link_alloc_cache(), rtnl_neigh_alloc_cache(), rtnl_neightbl_alloc_cache(), rtnl_qdisc_alloc_cache(), rtnl_route_alloc_cache(), and rtnl_rule_alloc_cache_by_family().

00174 {
00175         struct nl_cache *cache;
00176 
00177         cache = calloc(1, sizeof(*cache));
00178         if (!cache) {
00179                 nl_errno(ENOMEM);
00180                 return NULL;
00181         }
00182 
00183         nl_init_list_head(&cache->c_items);
00184         cache->c_ops = ops;
00185 
00186         NL_DBG(2, "Allocated cache %p <%s>.\n", cache, nl_cache_name(cache));
00187 
00188         return cache;
00189 }

struct nl_cache* nl_cache_alloc_name ( const char *  kind  )  [read]
Parameters:
kind Name of cache type
Returns:
A newly allocated and initialized cache.

Definition at line 196 of file cache.c.

References nl_cache_alloc(), and nl_cache_ops_lookup().

00197 {
00198         struct nl_cache_ops *ops;
00199 
00200         ops = nl_cache_ops_lookup(kind);
00201         if (!ops) {
00202                 nl_error(ENOENT, "Unable to lookup cache \"%s\"", kind);
00203                 return NULL;
00204         }
00205 
00206         return nl_cache_alloc(ops);
00207 }

struct nl_cache* nl_cache_subset ( struct nl_cache *  orig,
struct nl_object *  filter 
) [read]
Parameters:
orig Original cache to be based on
filter Filter defining the subset to be filled into new cache
Returns:
A newly allocated cache or NULL.

Definition at line 215 of file cache.c.

References nl_cache_add(), nl_cache_alloc(), and nl_object_match_filter().

00217 {
00218         struct nl_cache *cache;
00219         struct nl_object_ops *ops;
00220         struct nl_object *obj;
00221 
00222         if (!filter)
00223                 BUG();
00224 
00225         cache = nl_cache_alloc(orig->c_ops);
00226         if (!cache)
00227                 return NULL;
00228 
00229         ops = orig->c_ops->co_obj_ops;
00230 
00231         nl_list_for_each_entry(obj, &orig->c_items, ce_list) {
00232                 if (!nl_object_match_filter(obj, filter))
00233                         continue;
00234 
00235                 nl_cache_add(cache, obj);
00236         }
00237 
00238         return cache;
00239 }

void nl_cache_clear ( struct nl_cache *  cache  ) 
Parameters:
cache cache to clear

Removes all elements of a cache.

Definition at line 247 of file cache.c.

References nl_cache_remove().

Referenced by nl_cache_free(), and nl_cache_refill().

00248 {
00249         struct nl_object *obj, *tmp;
00250 
00251         NL_DBG(1, "Clearing cache %p <%s>...\n", cache, nl_cache_name(cache));
00252 
00253         nl_list_for_each_entry_safe(obj, tmp, &cache->c_items, ce_list)
00254                 nl_cache_remove(obj);
00255 }

void nl_cache_free ( struct nl_cache *  cache  ) 
Parameters:
cache Cache to free.

Removes all elements of a cache and frees all memory.

Note:
Use this function if you are working with allocated caches.

Definition at line 265 of file cache.c.

References nl_cache_clear().

Referenced by genl_ctrl_resolve(), nl_cache_mngr_add(), rtnl_class_alloc_cache(), rtnl_cls_alloc_cache(), rtnl_link_alloc_cache(), rtnl_neigh_alloc_cache(), rtnl_neightbl_alloc_cache(), and rtnl_qdisc_alloc_cache().

00266 {
00267         nl_cache_clear(cache);
00268         NL_DBG(1, "Freeing cache %p <%s>...\n", cache, nl_cache_name(cache));
00269         free(cache);
00270 }

int nl_cache_add ( struct nl_cache *  cache,
struct nl_object *  obj 
)
Parameters:
cache Cache to add object to
obj Object to be added to the cache

Adds the given object to the specified cache. The object is cloned if it has been added to another cache already.

Returns:
0 or a negative error code.

Definition at line 302 of file cache.c.

References nl_object_clone(), and nl_object_get().

Referenced by nl_cache_subset().

00303 {
00304         struct nl_object *new;
00305 
00306         if (cache->c_ops->co_obj_ops != obj->ce_ops)
00307                 return nl_error(EINVAL, "Object mismatches cache type");
00308 
00309         if (!nl_list_empty(&obj->ce_list)) {
00310                 new = nl_object_clone(obj);
00311                 if (!new)
00312                         return nl_errno(ENOMEM);
00313         } else {
00314                 nl_object_get(obj);
00315                 new = obj;
00316         }
00317 
00318         return __cache_add(cache, new);
00319 }

int nl_cache_move ( struct nl_cache *  cache,
struct nl_object *  obj 
)
Parameters:
cache Cache to move object to.
obj Object subject to be moved

Removes the given object from its associated cache if needed and adds it to the new cache.

Returns:
0 on success or a negative error code.

Definition at line 331 of file cache.c.

References nl_cache_remove(), and nl_object_get().

00332 {
00333         if (cache->c_ops->co_obj_ops != obj->ce_ops)
00334                 return nl_error(EINVAL, "Object mismatches cache type");
00335 
00336         NL_DBG(3, "Moving object %p to cache %p\n", obj, cache);
00337         
00338         /* Acquire reference, if already in a cache this will be
00339          * reverted during removal */
00340         nl_object_get(obj);
00341 
00342         if (!nl_list_empty(&obj->ce_list))
00343                 nl_cache_remove(obj);
00344 
00345         return __cache_add(cache, obj);
00346 }

void nl_cache_remove ( struct nl_object *  obj  ) 
Parameters:
obj Object to remove from its cache

Removes the object obj from the cache it is assigned to, since an object can only be assigned to one cache at a time, the cache must ne be passed along with it.

Definition at line 356 of file cache.c.

References nl_object_put().

Referenced by nl_cache_clear(), nl_cache_move(), and nl_object_free().

00357 {
00358         struct nl_cache *cache = obj->ce_cache;
00359 
00360         if (cache == NULL)
00361                 return;
00362 
00363         nl_list_del(&obj->ce_list);
00364         obj->ce_cache = NULL;
00365         nl_object_put(obj);
00366         cache->c_nitems--;
00367 
00368         NL_DBG(1, "Deleted %p from cache %p <%s>.\n",
00369                obj, cache, nl_cache_name(cache));
00370 }

struct nl_object* nl_cache_search ( struct nl_cache *  cache,
struct nl_object *  needle 
) [read]
Parameters:
cache Cache to search in.
needle Object to look for.

Iterates over the cache and looks for an object with identical identifiers as the needle.

Returns:
Reference to object or NULL if not found.
Note:
The returned object must be returned via nl_object_put().

Definition at line 383 of file cache.c.

References nl_object_get(), and nl_object_identical().

00385 {
00386         struct nl_object *obj;
00387 
00388         nl_list_for_each_entry(obj, &cache->c_items, ce_list) {
00389                 if (nl_object_identical(obj, needle)) {
00390                         nl_object_get(obj);
00391                         return obj;
00392                 }
00393         }
00394 
00395         return NULL;
00396 }

int nl_cache_request_full_dump ( struct nl_handle *  handle,
struct nl_cache *  cache 
)
Parameters:
handle Netlink handle
cache Cache subjected to be filled.

Send a dumping request to the kernel causing it to dump all objects related to the specified cache to the netlink socket.

Use nl_cache_pickup() to read the objects from the socket and fill them into a cache.

Definition at line 417 of file cache.c.

Referenced by nl_cache_refill().

00418 {
00419         NL_DBG(2, "Requesting dump from kernel for cache %p <%s>...\n",
00420                   cache, nl_cache_name(cache));
00421 
00422         if (cache->c_ops->co_request_update == NULL)
00423                 return nl_error(EOPNOTSUPP, "Operation not supported");
00424 
00425         return cache->c_ops->co_request_update(cache, handle);
00426 }

int nl_cache_pickup ( struct nl_handle *  handle,
struct nl_cache *  cache 
)
Parameters:
handle Netlink handle.
cache Cache to put items into.

Waits for netlink messages to arrive, parses them and puts them into the specified cache.

Returns:
0 on success or a negative error code.

Definition at line 487 of file cache.c.

Referenced by flnl_lookup(), and nl_cache_refill().

00488 {
00489         struct nl_parser_param p = {
00490                 .pp_cb = pickup_cb,
00491                 .pp_arg = cache,
00492         };
00493 
00494         return __cache_pickup(handle, cache, &p);
00495 }

int nl_cache_parse_and_add ( struct nl_cache *  cache,
struct nl_msg *  msg 
)
Parameters:
cache cache to add element to
msg netlink message

Parses a netlink message by calling the cache specific message parser and adds the new element to the cache.

Returns:
0 or a negative error code.

Definition at line 642 of file cache.c.

References nlmsg_hdr().

00643 {
00644         struct nl_parser_param p = {
00645                 .pp_cb = pickup_cb,
00646                 .pp_arg = cache,
00647         };
00648 
00649         return nl_cache_parse(cache->c_ops, NULL, nlmsg_hdr(msg), &p);
00650 }

int nl_cache_refill ( struct nl_handle *  handle,
struct nl_cache *  cache 
)
Parameters:
handle netlink handle
cache cache to update

Clears the specified cache and fills it with the current state in the kernel.

Returns:
0 or a negative error code.

Definition at line 662 of file cache.c.

References nl_cache_clear(), nl_cache_pickup(), and nl_cache_request_full_dump().

Referenced by nfnl_ct_alloc_cache(), nl_cache_mngr_add(), rtnl_class_alloc_cache(), rtnl_cls_alloc_cache(), rtnl_link_alloc_cache(), rtnl_neigh_alloc_cache(), rtnl_neightbl_alloc_cache(), rtnl_qdisc_alloc_cache(), rtnl_route_alloc_cache(), and rtnl_rule_alloc_cache_by_family().

00663 {
00664         int err;
00665 
00666         err = nl_cache_request_full_dump(handle, cache);
00667         if (err < 0)
00668                 return err;
00669 
00670         NL_DBG(2, "Upading cache %p <%s>, request sent, waiting for dump...\n",
00671                cache, nl_cache_name(cache));
00672         nl_cache_clear(cache);
00673 
00674         return nl_cache_pickup(handle, cache);
00675 }

void nl_cache_mark_all ( struct nl_cache *  cache  ) 
Parameters:
cache Cache to mark all objects in

Definition at line 688 of file cache.c.

References nl_object_mark().

00689 {
00690         struct nl_object *obj;
00691 
00692         NL_DBG(2, "Marking all objects in cache %p <%s>...\n",
00693                   cache, nl_cache_name(cache));
00694 
00695         nl_list_for_each_entry(obj, &cache->c_items, ce_list)
00696                 nl_object_mark(obj);
00697 }

void nl_cache_dump ( struct nl_cache *  cache,
struct nl_dump_params params 
)
Parameters:
cache cache to dump
params dumping parameters

Dumps all elements of the cache to the file descriptor fd.

Definition at line 713 of file cache.c.

References nl_cache_dump_filter().

00714 {
00715         nl_cache_dump_filter(cache, params, NULL);
00716 }

void nl_cache_dump_filter ( struct nl_cache *  cache,
struct nl_dump_params params,
struct nl_object *  filter 
)
Parameters:
cache cache to dump
params dumping parameters (optional)
filter filter object

Dumps all elements of the cache to the file descriptor fd given they match the given filter filter.

Definition at line 727 of file cache.c.

References nl_dump_params::dp_type, NL_DUMP_FULL, nl_object_match_filter(), and nl_object_ops::oo_dump.

Referenced by nl_cache_dump().

00730 {
00731         int type = params ? params->dp_type : NL_DUMP_FULL;
00732         struct nl_object_ops *ops;
00733         struct nl_object *obj;
00734 
00735         NL_DBG(2, "Dumping cache %p <%s> filter %p\n",
00736                cache, nl_cache_name(cache), filter);
00737 
00738         if (type > NL_DUMP_MAX || type < 0)
00739                 BUG();
00740 
00741         if (cache->c_ops == NULL)
00742                 BUG();
00743 
00744         ops = cache->c_ops->co_obj_ops;
00745         if (!ops->oo_dump[type])
00746                 return;
00747 
00748         nl_list_for_each_entry(obj, &cache->c_items, ce_list) {
00749                 if (filter && !nl_object_match_filter(obj, filter))
00750                         continue;
00751 
00752                 NL_DBG(4, "Dumping object %p...\n", obj);
00753                 dump_from_ops(obj, params);
00754         }
00755 }

void nl_cache_foreach ( struct nl_cache *  cache,
void(*)(struct nl_object *, void *)  cb,
void *  arg 
)
Parameters:
cache cache to iterate on
cb callback function
arg argument passed to callback function

Calls a callback function cb on each element of the cache. The argument arg is passed on the callback function.

Definition at line 773 of file cache.c.

References nl_cache_foreach_filter().

00775 {
00776         nl_cache_foreach_filter(cache, NULL, cb, arg);
00777 }

void nl_cache_foreach_filter ( struct nl_cache *  cache,
struct nl_object *  filter,
void(*)(struct nl_object *, void *)  cb,
void *  arg 
)
Parameters:
cache cache to iterate on
filter filter object
cb callback function
arg argument passed to callback function

Calls a callback function cb on each element of the cache that matches the filter. The argument arg is passed on to the callback function.

Definition at line 790 of file cache.c.

References nl_object_match_filter().

Referenced by nl_cache_foreach(), rtnl_class_foreach_child(), rtnl_class_foreach_cls(), rtnl_qdisc_foreach_child(), and rtnl_qdisc_foreach_cls().

00792 {
00793         struct nl_object *obj, *tmp;
00794         struct nl_object_ops *ops;
00795 
00796         if (cache->c_ops == NULL)
00797                 BUG();
00798 
00799         ops = cache->c_ops->co_obj_ops;
00800 
00801         nl_list_for_each_entry_safe(obj, tmp, &cache->c_items, ce_list) {
00802                 if (filter && !nl_object_match_filter(obj, filter))
00803                         continue;
00804 
00805                 cb(obj, arg);
00806         }
00807 }


Generated on 30 Oct 2009 for libnl by  doxygen 1.6.1