cmap_track_add - Set tracking function for values in CMAP
#include <corosync/cmap.h>
cs_error_t cmap_track_add (cmap_handle_t handle, const
char * key_name, int32_t track_type,
cmap_notify_fn_t notify_fn, void *user_data,
cmap_track_handle_t * cmap_track_handle);
The
cmap_track_add function is used to set function which tracks changes
in CMAP. One CMAP connection can track multiple keys and also it's possible to
track one key multiple times. The
handle argument is connection to CMAP
database obtained by calling
cmap_initialize(3) function.
key_name argument is ether exact key name or prefix of key name to
track changes on.
track_type is bitfield which may consist of following
values:
CMAP_TRACK_ADD - track addition of new key (or key added in callback)
CMAP_TRACK_DELETE - track deletion of key (or key deleted in callback)
CMAP_TRACK_MODIFY - track modification of key (or key modified in
callback)
CMAP_TRACK_PREFIX - whole prefix is tracked, instead of key only, so
"totem." tracking means that "totem.nodeid",
"totem.version", ... applies (this value is never returned in
callback)
notify_fn is pointer to function which is called when value is changed.
It's definition and meaning of parameters is discussed below.
user_data
argument is passed directly to
notify_fn without any changes.
cmap_track_handle is used for removing of tracking when no longer
needed by calling
cmap_track_delete(3) function.
Callback function is defined as:
typedef void (*cmap_notify_fn_t) (
cmap_handle_t cmap_handle,
cmap_track_handle_t cmap_track_handle,
int32_t event,
const char *key_name,
struct cmap_notify_value new_value,
struct cmap_notify_value old_value,
void *user_data);
where
cmap_handle is handle used in registration of track function.
cmap_track_handle is handle returned by
cmap_track_add function.
event is one of
CMAP_TRACK_ADD,
CMAP_TRACK_DELETE or
CMAP_TRACK_MODIFY.
key_name is name of changed key.
new_value is new value of key, or unset if
event is
CMAP_TRACK_DELETE.
old_value is previous value of key or unset
if
event is
CMAP_TRACK_ADD or for some special keys set directly
by Corosync due to speed optimizations. Both
new_value and
old_value are structures defined as:
struct cmap_notify_value {
cmap_value_types_t type;
size_t len;
const void *data;
};
If value is unset, all fields are set to 0. Otherwise
type is one of cmap
types (as described in
cmap_get(3) function),
len is length of
value in cmap and
data is pointer to value of item. Data storage is
dynamically allocated by caller and notify function must not try to free it.
This call returns the CS_OK value if successful. It can return
CS_ERR_INVALID_PARAM if notify_fn is NULL or track_type is invalid value.
Modification tracking of individual keys is supported in the stats map, but not
prefixes. Add/Delete operations are supported on prefixes though so you can
track for new ipc connections or knet interfaces. In the icmap map, prefix
tracking is fully supported.
cmap_track_delete(3),
cmap_initialize(3),
cmap_get(3),
cmap_dispatch(3),
cmap_overview(3)
CS_ERR_TRY_AGAIN Resource temporarily unavailable
CS_ERR_INVALID_PARAM Invalid argument
CS_ERR_ACCESS Permission denied
CS_ERR_LIBRARY The connection failed
CS_ERR_INTERRUPT System call interrupted by a signal
CS_ERR_NOT_SUPPORTED The requested protocol/functionality not supported
CS_ERR_MESSAGE_ERROR Incorrect auth message received
CS_ERR_NO_MEMORY Not enough memory to complete the requested task