Cache

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_ops *	nl_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_get (struct nl_cache *cache)
	Increase reference counter of 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

nl_cache_nitems()

int nl_cache_nitems

(

struct nl_cache *

cache

)

Parameters

cache

cache handle

Definition at line 58 of file cache.c.

{
        return cache->c_nitems;
}

nl_cache_nitems_filter()

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.

{
        struct nl_object *obj;
        int nitems = 0;
 
        if (cache->c_ops == NULL)
                BUG();
 
        nl_list_for_each_entry(obj, &cache->c_items, ce_list) {
                if (filter && !nl_object_match_filter(obj, filter))
                        continue;
 
                nitems++;
        }
 
        return nitems;
}

References nl_object_match_filter().

nl_cache_is_empty()

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 91 of file cache.c.

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

nl_cache_get_ops()

struct nl_cache_ops * nl_cache_get_ops

(

struct nl_cache *

cache

)

Parameters

cache

cache handle

Definition at line 100 of file cache.c.

{
        return cache->c_ops;
}

nl_cache_get_first()

struct nl_object * nl_cache_get_first

(

struct nl_cache *

cache

)

Parameters

cache

cache handle

Definition at line 109 of file cache.c.

{
        if (nl_list_empty(&cache->c_items))
                return NULL;
 
        return nl_list_entry(cache->c_items.next,
                             struct nl_object, ce_list);
}

nl_cache_get_last()

struct nl_object * nl_cache_get_last

(

struct nl_cache *

cache

)

Parameters

cache

cache handle

Definition at line 122 of file cache.c.

{
        if (nl_list_empty(&cache->c_items))
                return NULL;
 
        return nl_list_entry(cache->c_items.prev,
                             struct nl_object, ce_list);
}

nl_cache_get_next()

struct nl_object * nl_cache_get_next

(

struct nl_object *

obj

)

Parameters

obj	current object

Definition at line 135 of file cache.c.

{
        if (nl_list_at_tail(obj, &obj->ce_cache->c_items, ce_list))
                return NULL;
        else
                return nl_list_entry(obj->ce_list.next,
                                     struct nl_object, ce_list);
}

nl_cache_get_prev()

struct nl_object * nl_cache_get_prev

(

struct nl_object *

obj

)

Parameters

obj	current object

Definition at line 148 of file cache.c.

{
        if (nl_list_at_head(obj, &obj->ce_cache->c_items, ce_list))
                return NULL;
        else
                return nl_list_entry(obj->ce_list.prev,
                                     struct nl_object, ce_list);
}

nl_cache_alloc()

struct nl_cache * nl_cache_alloc

(

struct nl_cache_ops *

ops

)

Parameters

ops	cache operations to base the cache on

Returns

A newly allocated and initialized cache.

Definition at line 170 of file cache.c.

{
        struct nl_cache *cache;
 
        cache = calloc(1, sizeof(*cache));
        if (!cache) {
                nl_errno(ENOMEM);
                return NULL;
        }
 
        nl_init_list_head(&cache->c_items);
        cache->c_ops = ops;
        cache->c_refcnt = 1;
 
        NL_DBG(2, "Allocated cache %p <%s>.\n", cache, nl_cache_name(cache));
 
        return cache;
}

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().

nl_cache_alloc_name()

struct nl_cache * nl_cache_alloc_name

(

const char *

kind

)

Parameters

kind	Name of cache type

Returns

A newly allocated and initialized cache.

Definition at line 194 of file cache.c.

{
        struct nl_cache_ops *ops;
 
        ops = nl_cache_ops_lookup(kind);
        if (!ops) {
                nl_error(ENOENT, "Unable to lookup cache \"%s\"", kind);
                return NULL;
        }
 
        return nl_cache_alloc(ops);
}

References nl_cache_alloc(), and nl_cache_ops_lookup().

nl_cache_subset()

struct nl_cache * nl_cache_subset	(	struct nl_cache *	orig,
		struct nl_object *	filter
	)

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 213 of file cache.c.

{
        struct nl_cache *cache;
        struct nl_object *obj;
 
        if (!filter)
                BUG();
 
        cache = nl_cache_alloc(orig->c_ops);
        if (!cache)
                return NULL;
 
        nl_list_for_each_entry(obj, &orig->c_items, ce_list) {
                if (!nl_object_match_filter(obj, filter))
                        continue;
 
                nl_cache_add(cache, obj);
        }
 
        return cache;
}

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

nl_cache_clear()

void nl_cache_clear

(

struct nl_cache *

cache

)

Parameters

cache

cache to clear

Removes all elements of a cache.

Definition at line 242 of file cache.c.

{
        struct nl_object *obj, *tmp;
 
        NL_DBG(1, "Clearing cache %p <%s>...\n", cache, nl_cache_name(cache));
 
        nl_list_for_each_entry_safe(obj, tmp, &cache->c_items, ce_list)
                nl_cache_remove(obj);
}

References nl_cache_remove().

Referenced by nl_cache_refill().

nl_cache_get()

void nl_cache_get

(

struct nl_cache *

cache

)

Parameters

cache

Cache

Definition at line 264 of file cache.c.

{
        cache->c_refcnt++;
}

Referenced by nl_cache_mngt_provide().

nl_cache_free()

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 277 of file cache.c.

{
        if (!cache)
                return;
 
        cache->c_refcnt--;
        NL_DBG(4, "Returned cache reference %p, %d remaining\n",
               cache, cache->c_refcnt);
 
        if (cache->c_refcnt <= 0)
                __nl_cache_free(cache);
}

Referenced by genl_ctrl_resolve(), nl_cache_mngr_add(), nl_cache_mngt_unprovide(), 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().

nl_cache_add()

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 320 of file cache.c.

{
        struct nl_object *new;
 
        if (cache->c_ops->co_obj_ops != obj->ce_ops)
                return nl_error(EINVAL, "Object mismatches cache type");
 
        if (!nl_list_empty(&obj->ce_list)) {
                new = nl_object_clone(obj);
                if (!new)
                        return nl_errno(ENOMEM);
        } else {
                nl_object_get(obj);
                new = obj;
        }
 
        return __cache_add(cache, new);
}

References nl_object_clone(), and nl_object_get().

Referenced by nl_cache_subset().

nl_cache_move()

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 349 of file cache.c.

{
        if (cache->c_ops->co_obj_ops != obj->ce_ops)
                return nl_error(EINVAL, "Object mismatches cache type");
 
        NL_DBG(3, "Moving object %p to cache %p\n", obj, cache);
        
        /* Acquire reference, if already in a cache this will be
         * reverted during removal */
        nl_object_get(obj);
 
        if (!nl_list_empty(&obj->ce_list))
                nl_cache_remove(obj);
 
        return __cache_add(cache, obj);
}

References nl_cache_remove(), and nl_object_get().

nl_cache_remove()

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 374 of file cache.c.

{
        struct nl_cache *cache = obj->ce_cache;
 
        if (cache == NULL)
                return;
 
        nl_list_del(&obj->ce_list);
        obj->ce_cache = NULL;
        nl_object_put(obj);
        cache->c_nitems--;
 
        NL_DBG(1, "Deleted %p from cache %p <%s>.\n",
               obj, cache, nl_cache_name(cache));
}

References nl_object_put().

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

nl_cache_search()

struct nl_object * nl_cache_search	(	struct nl_cache *	cache,
		struct nl_object *	needle
	)

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 401 of file cache.c.

{
        struct nl_object *obj;
 
        nl_list_for_each_entry(obj, &cache->c_items, ce_list) {
                if (nl_object_identical(obj, needle)) {
                        nl_object_get(obj);
                        return obj;
                }
        }
 
        return NULL;
}

References nl_object_get(), and nl_object_identical().

nl_cache_request_full_dump()

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 435 of file cache.c.

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

Referenced by nl_cache_refill().

__cache_pickup()

int __cache_pickup	(	struct nl_handle *	handle,
		struct nl_cache *	cache,
		struct nl_parser_param *	param
	)

Definition at line 460 of file cache.c.

{
        int err;
        struct nl_cb *cb;
        struct update_xdata x = {
                .ops = cache->c_ops,
                .params = param,
        };
 
        NL_DBG(1, "Picking up answer for cache %p <%s>...\n",
                  cache, nl_cache_name(cache));
 
        cb = nl_cb_clone(handle->h_cb);
        if (cb == NULL)
                return nl_get_errno();
 
        nl_cb_set(cb, NL_CB_VALID, NL_CB_CUSTOM, update_msg_parser, &x);
 
        err = nl_recvmsgs(handle, cb);
        if (err < 0)
                NL_DBG(2, "While picking up for %p <%s>, recvmsgs() returned " \
                       "%d: %s", cache, nl_cache_name(cache),
                       err, nl_geterror());
 
        nl_cb_put(cb);
 
        return err;
}

nl_cache_pickup()

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 505 of file cache.c.

{
        struct nl_parser_param p = {
                .pp_cb = pickup_cb,
                .pp_arg = cache,
        };
 
        return __cache_pickup(handle, cache, &p);
}

Referenced by flnl_lookup(), and nl_cache_refill().

nl_cache_include()

int nl_cache_include	(	struct nl_cache *	cache,
		struct nl_object *	obj,
		change_func_t	change_cb
	)

Definition at line 553 of file cache.c.

{
        struct nl_cache_ops *ops = cache->c_ops;
        int i;
 
        if (ops->co_obj_ops != obj->ce_ops)
                return nl_error(EINVAL, "Object mismatches cache type");
 
        for (i = 0; ops->co_msgtypes[i].mt_id >= 0; i++)
                if (ops->co_msgtypes[i].mt_id == obj->ce_msgtype)
                        return cache_include(cache, obj, &ops->co_msgtypes[i],
                                             change_cb);
 
        return nl_errno(EINVAL);
}

nl_cache_resync()

int nl_cache_resync	(	struct nl_handle *	handle,
		struct nl_cache *	cache,
		change_func_t	change_cb
	)

Definition at line 577 of file cache.c.

{
        struct nl_object *obj, *next;
        struct nl_cache_assoc ca = {
                .ca_cache = cache,
                .ca_change = change_cb,
        };
        struct nl_parser_param p = {
                .pp_cb = resync_cb,
                .pp_arg = &ca,
        };
        int err;
 
        NL_DBG(1, "Resyncing cache %p <%s>...\n", cache, nl_cache_name(cache));
 
        /* Mark all objects so we can see if some of them are obsolete */
        nl_cache_mark_all(cache);
 
        err = nl_cache_request_full_dump(handle, cache);
        if (err < 0)
                goto errout;
 
        err = __cache_pickup(handle, cache, &p);
        if (err < 0)
                goto errout;
 
        nl_list_for_each_entry_safe(obj, next, &cache->c_items, ce_list)
                if (nl_object_is_marked(obj))
                        nl_cache_remove(obj);
 
        NL_DBG(1, "Finished resyncing %p <%s>\n", cache, nl_cache_name(cache));
 
        err = 0;
errout:
        return err;
}

nl_cache_parse_and_add()

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 660 of file cache.c.

{
        struct nl_parser_param p = {
                .pp_cb = pickup_cb,
                .pp_arg = cache,
        };
 
        return nl_cache_parse(cache->c_ops, NULL, nlmsg_hdr(msg), &p);
}

References nlmsg_hdr().

nl_cache_refill()

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 680 of file cache.c.

{
        int err;
 
        err = nl_cache_request_full_dump(handle, cache);
        if (err < 0)
                return err;
 
        NL_DBG(2, "Upading cache %p <%s>, request sent, waiting for dump...\n",
               cache, nl_cache_name(cache));
        nl_cache_clear(cache);
 
        return nl_cache_pickup(handle, cache);
}

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().

nl_cache_mark_all()

void nl_cache_mark_all

(

struct nl_cache *

cache

)

Parameters

cache

Cache to mark all objects in

Definition at line 706 of file cache.c.

{
        struct nl_object *obj;
 
        NL_DBG(2, "Marking all objects in cache %p <%s>...\n",
                  cache, nl_cache_name(cache));
 
        nl_list_for_each_entry(obj, &cache->c_items, ce_list)
                nl_object_mark(obj);
}

References nl_object_mark().

nl_cache_dump()

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 731 of file cache.c.

{
        nl_cache_dump_filter(cache, params, NULL);
}

References nl_cache_dump_filter().

nl_cache_dump_filter()

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 745 of file cache.c.

{
        int type = params ? params->dp_type : NL_DUMP_FULL;
        struct nl_object_ops *ops;
        struct nl_object *obj;
 
        NL_DBG(2, "Dumping cache %p <%s> filter %p\n",
               cache, nl_cache_name(cache), filter);
 
        if (type > NL_DUMP_MAX || type < 0)
                BUG();
 
        if (cache->c_ops == NULL)
                BUG();
 
        ops = cache->c_ops->co_obj_ops;
        if (!ops->oo_dump[type])
                return;
 
        nl_list_for_each_entry(obj, &cache->c_items, ce_list) {
                if (filter && !nl_object_match_filter(obj, filter))
                        continue;
 
                NL_DBG(4, "Dumping object %p...\n", obj);
                dump_from_ops(obj, params);
        }
}

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

Referenced by nl_cache_dump().

nl_cache_foreach()

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 791 of file cache.c.

{
        nl_cache_foreach_filter(cache, NULL, cb, arg);
}

References nl_cache_foreach_filter().

nl_cache_foreach_filter()

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 808 of file cache.c.

{
        struct nl_object *obj, *tmp;
 
        if (cache->c_ops == NULL)
                BUG();
 
        nl_list_for_each_entry_safe(obj, tmp, &cache->c_items, ce_list) {
                if (filter && !nl_object_match_filter(obj, filter))
                        continue;
 
                cb(obj, arg);
        }
}

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().