libnl: Manager

libnl 3.7.0

Functions
Manager
Core Library (libnl) » Caching System

Manager keeping caches up to date automatically. More...

## Functions
int | nl_cache_mngr_alloc (struct nl_sock *sk, int protocol, int flags, struct nl_cache_mngr **result)
| Allocate new cache manager. More...
int | nl_cache_mngr_add_cache (struct nl_cache_mngr *mngr, struct nl_cache *cache, change_func_t cb, void *data)
| Add cache to cache manager. More...
int | nl_cache_mngr_add_cache_v2 (struct nl_cache_mngr *mngr, struct nl_cache *cache, change_func_v2_t cb, void *data)
| Add cache to cache manager. More...
int | nl_cache_mngr_add (struct nl_cache_mngr *mngr, const char *name, change_func_t cb, void *data, struct nl_cache **result)
| Add cache to cache manager. More...
int | nl_cache_mngr_get_fd (struct nl_cache_mngr *mngr)
| Get socket file descriptor. More...
int | nl_cache_mngr_poll (struct nl_cache_mngr *mngr, int timeout)
| Check for event notifications. More...
int | nl_cache_mngr_data_ready (struct nl_cache_mngr *mngr)
| Receive available event notifications. More...
void | nl_cache_mngr_info (struct nl_cache_mngr *mngr, struct nl_dump_params *p)
| Print information about cache manager. More...
void | nl_cache_mngr_free (struct nl_cache_mngr *mngr)
| Free cache manager and all caches. More...

## Detailed Description

Manager keeping caches up to date automatically.

The cache manager keeps caches up to date automatically by listening to netlink notifications and integrating the received information into the existing cache.

Note
  This functionality is still considered experimental.

Related sections in the development guide:

- Cache Manager (Netlink Core Library Development Guide)

## Header

#include <netlink/cache.h>

## Function Documentation

## ◆ nl_cache_mngr_alloc()

int nl_cache_mngr_alloc | ( | struct nl_sock * | sk,
|  | int | protocol,
|  | int | flags,
|  | struct nl_cache_mngr ** | result
| ) |  |

Allocate new cache manager.

Parameters

  sk | Netlink socket or NULL to auto allocate
  protocol | Netlink protocol this manager is used for
  flags | Flags (`NL_AUTO_PROVIDE`)
  result | Result pointer

Allocates a new cache manager for the specified netlink protocol.

1. If sk is not specified (`NULL`) a netlink socket matching the specified protocol will be automatically allocated.
2. The socket will be put in non-blocking mode and sequence checking will be disabled regardless of whether the socket was provided by the caller or automatically allocated.
3. The socket will be connected.

If the flag `NL_AUTO_PROVIDE` is specified, any cache added to the manager will automatically be made available to other users using nl_cache_mngt_provide().

Note
  If the socket is provided by the caller, it is NOT recommended to use the socket for anything else besides receiving netlink notifications.

Returns
  0 on success or a negative error code.

Definition at line 136 of file cache_mngr.c.

References nl_cache_mngr_free(), nl_connect(), nl_socket_alloc(), nl_socket_disable_seq_check(), nl_socket_free(), and nl_socket_set_nonblocking().

Here is the call graph for this function:

## ◆ nl_cache_mngr_add_cache()

int nl_cache_mngr_add_cache | ( | struct nl_cache_mngr * | mngr,
|  | struct nl_cache * | cache,
|  | change_func_t | cb,
|  | void * | data
| ) |  |

Add cache to cache manager.

Parameters

  mngr | Cache manager.
  cache | Cache to be added to cache manager
  cb | Function to be called upon changes.
  data | Argument passed on to change callback

Adds cache to the manager. The operation will trigger a full dump request from the kernel to initially fill the contents of the cache. The manager will subscribe to the notification group of the cache and keep track of any further changes.

The user is responsible for calling nl_cache_mngr_poll() or monitor the socket and call nl_cache_mngr_data_ready() to allow the library to process netlink notification events.

See also
  nl_cache_mngr_poll()
  nl_cache_mngr_data_ready()

Returns
  0 on success or a negative error code.
  -NLE_PROTO_MISMATCH Protocol mismatch between cache manager and cache type
  -NLE_OPNOTSUPP Cache type does not support updates
  -NLE_EXIST Cache of this type already being managed

Definition at line 286 of file cache_mngr.c.

Referenced by nl_cache_mngr_add(), and nl_cache_mngr_add_cache_v2().

Here is the caller graph for this function:

## ◆ nl_cache_mngr_add_cache_v2()

int nl_cache_mngr_add_cache_v2 | ( | struct nl_cache_mngr * | mngr,
|  | struct nl_cache * | cache,
|  | change_func_v2_t | cb,
|  | void * | data
| ) |  |

Add cache to cache manager.

Parameters

  mngr | Cache manager.
  cache | Cache to be added to cache manager
  cb | V2 function to be called upon changes.
  data | Argument passed on to change callback

Adds cache to the manager. The operation will trigger a full dump request from the kernel to initially fill the contents of the cache. The manager will subscribe to the notification group of the cache and keep track of any further changes.

The user is responsible for calling nl_cache_mngr_poll() or monitor the socket and call nl_cache_mngr_data_ready() to allow the library to process netlink notification events.

See also
  nl_cache_mngr_poll()
  nl_cache_mngr_data_ready()

Returns
  0 on success or a negative error code.
  -NLE_PROTO_MISMATCH Protocol mismatch between cache manager and cache type
  -NLE_OPNOTSUPP Cache type does not support updates
  -NLE_EXIST Cache of this type already being managed

Definition at line 384 of file cache_mngr.c.

References nl_cache_mngr_add_cache().

Here is the call graph for this function:

## ◆ nl_cache_mngr_add()

int nl_cache_mngr_add | ( | struct nl_cache_mngr * | mngr,
|  | const char * | name,
|  | change_func_t | cb,
|  | void * | data,
|  | struct nl_cache ** | result
| ) |  |

Add cache to cache manager.

Parameters

  mngr | Cache manager.
  name | Name of cache to keep track of
  cb | Function to be called upon changes.
  data | Argument passed on to change callback
  result | Pointer to store added cache (optional)

Allocates a new cache of the specified type and adds it to the manager. The operation will trigger a full dump request from the kernel to initially fill the contents of the cache. The manager will subscribe to the notification group of the cache and keep track of any further changes.

The user is responsible for calling nl_cache_mngr_poll() or monitor the socket and call nl_cache_mngr_data_ready() to allow the library to process netlink notification events.

Note
  Versions up to 3.4.0 actually required the result argument, preventing NULL to be passed.

See also
  nl_cache_mngr_poll()
  nl_cache_mngr_data_ready()

Returns
  0 on success or a negative error code.
  -NLE_NOCACHE Unknown cache type
  -NLE_PROTO_MISMATCH Protocol mismatch between cache manager and cache type
  -NLE_OPNOTSUPP Cache type does not support updates
  -NLE_EXIST Cache of this type already being managed

Definition at line 425 of file cache_mngr.c.

References nl_cache_alloc(), nl_cache_free(), nl_cache_mngr_add_cache(), nl_cache_ops_lookup_safe(), and nl_cache_ops_put().

Here is the call graph for this function:

## ◆ nl_cache_mngr_get_fd()

int nl_cache_mngr_get_fd | ( | struct nl_cache_mngr * | mngr | ) |

Get socket file descriptor.

Parameters

  mngr | Cache Manager

Get the file descriptor of the socket associated with the manager.

Note
  Do not use the socket for anything besides receiving notifications.

Definition at line 464 of file cache_mngr.c.

References nl_socket_get_fd().

Here is the call graph for this function:

## ◆ nl_cache_mngr_poll()

int nl_cache_mngr_poll | ( | struct nl_cache_mngr * | mngr,
|  | int | timeout
| ) |  |

Check for event notifications.

Parameters

  mngr | Cache Manager
  timeout | Upper limit poll() will block, in milliseconds.

Causes poll() to be called to check for new event notifications being available. Calls nl_cache_mngr_data_ready() to process available data.

This functionally is ideally called regularly during an idle period.

A timeout can be specified in milliseconds to limit the time the function will wait for updates.

See also
  nl_cache_mngr_data_ready()

Returns
  The number of messages processed or a negative error code.

Definition at line 488 of file cache_mngr.c.

References nl_cache_mngr_data_ready(), and nl_socket_get_fd().

Here is the call graph for this function:

## ◆ nl_cache_mngr_data_ready()

int nl_cache_mngr_data_ready | ( | struct nl_cache_mngr * | mngr | ) |

Receive available event notifications.

Parameters

  mngr | Cache manager

This function can be called if the socket associated to the manager contains updates to be received. This function should only be used if nl_cache_mngr_poll() is not used.

The function will process messages until there is no more data to be read from the socket.

See also
  nl_cache_mngr_poll()

Returns
  The number of messages processed or a negative error code.

Definition at line 527 of file cache_mngr.c.

References nl_cb_clone(), NL_CB_CUSTOM, nl_cb_set(), NL_CB_VALID, and nl_socket_get_fd().

Referenced by nl_cache_mngr_poll().

Here is the call graph for this function:
Here is the caller graph for this function:

## ◆ nl_cache_mngr_info()

void nl_cache_mngr_info | ( | struct nl_cache_mngr * | mngr,
|  | struct nl_dump_params * | p
| ) |  |

Print information about cache manager.

Parameters

  mngr | Cache manager
  p | Dumping parameters

Prints information about the cache manager including all managed caches.

Note
  This is a debugging function.

Definition at line 563 of file cache_mngr.c.

## ◆ nl_cache_mngr_free()

void nl_cache_mngr_free | ( | struct nl_cache_mngr * | mngr | ) |

Free cache manager and all caches.

Parameters

  mngr | Cache manager.

Release all resources held by a cache manager.

Definition at line 602 of file cache_mngr.c.

References nl_cache_free(), nl_cache_mngt_unprovide(), nl_close(), and nl_socket_free().

Referenced by nl_cache_mngr_alloc().

Here is the call graph for this function:
Here is the caller graph for this function: