kstat2_map_set_tree_cb, kstat2_map_set_data_cb, kstat2_map_set_destroy_cb - kstat2 tree mutation callbacks
cc [ flag... ] file... -lkstat2 [ library...]
#include <kstat2.h>
kstat2_status_t kstat2_map_set_tree_cb(kstat2_map_t map,
kstat2_tree_cb_t callback);
kstat2_status_t kstat2_map_set_data_cb(kstat2_map_t map,
kstat2_data_cb_t callback);
kstat2_status_t kstat2_map_set_destroy_cb(kstat2_map_t map,
kstat2_map_cb_t callback);
kstat2_map_set_tree_cb() establishes a callback function that will be called whenever a kstat2 map is added or removed to the tree below the specified map. The callback must conform to the following typedef:
typedef void (*kstat2_tree_cb_t)(kstat2_map_t map,
kstat2_map_t sub_map, kstat2_tree_cb_event_t event);
The callback will be passed the map it was registered against and the sub-map that has just been created or is about to be destroyed. To remove the callback, a callback parameter of NULL can be passed to kstat2_map_set_tree_cb(). The third parameter identifies the operation as an addition or a deletion event:
typedef enum kstat2_tree_cb_event {
KSTAT2_TREE_ADD = 0,
KSTAT2_TREE_REM = 1
} kstat2_tree_cb_event_t;
This callback may only access the user data and sub-map items in any map, see the descriptions of KSTAT2_NVK_SYS, KSTAT2_NVK_USR, and KSTAT2_NVK_MAP in kstat2(3KSTAT2) for details.
kstat2_map_set_data_cb() establishes a callback function that will be called whenever kernel kstat data is added to or removed from the current map and any map in the tree below it. The callback must conform to the following typedef:
typedef void (*kstat2_data_cb_t)(kstat2_map_t map,
kstat2_map_t sub_map, kstat2_data_cb_event_t event);
The callback will be passed the map it was registered against and the sub-map to which kstat data is being added or removed. To remove the callback, a callback parameter of NULL can be passed to kstat2_map_set_data_cb().
typedef enum kstat2_data_cb_event {
KSTAT2_DATA_ADD = 0,
KSTAT2_DATA_REM = 1
} kstat2_data_cb_event_t;
If the event parameter is KSTAT2_DATA_ADD, this callback may access all data items in any map. If the event parameter is KSTAT2_DATA_REM it can only access user data and sub-map items in any map. See the descriptions of KSTAT2_NVK_SYS, KSTAT2_NVK_USR, and KSTAT2_NVK_MAP in kstat2(3KSTAT2) for details.
kstat2_map_set_destroy_cb() establishes a callback that will be called immediately prior to the deletion of a kstat map. The callback must conform to the following typedef:
typedef void (*kstat2_map_cb_t)(kstat2_map_t map, void *user_data);
The callback will be passed the map it was registered against and any user data that has been associated with the map (see kstat2_map_set_userdata(3KSTAT2)), or NULL if there is no such data. To remove the callback, a callback parameter of NULL can be passed. This callback may be used to reclaim any resources associated with a map, for example, logging filehandles or external structure references.
This callback may only access the user data and sub-map items in any map, see the descriptions of KSTAT2_NVK_SYS, KSTAT2_NVK_USR, and KSTAT2_NVK_MAP in kstat2(3KSTAT2) for details.
The ordering of callbacks over the lifecycle of a map will be:
tree callback
data callback
data callback and destroy callback
All callbacks are made synchronously during kstat2_update() and callbacks that take a significant time to execute will stall the execution of kstat2_update(). Long running processing should therefore be deferred and performed outside of the callback functions.
On successful completion, the kstat2_map_set_tree_cb(), kstat2_map_set_data_cb(), and kstat2_map_set_destroy_cb() will return KSTAT2_S_OK.
The kstat2_map_set_tree_cb(), kstat2_map_set_data_cb(), and kstat2_map_set_destroy_cb() functions will fail if:
the map parameter is NULL
kernel statistics driver
header
See the kstat2(3KSTAT2) manpage.
See attributes(7) for descriptions of the following attributes:
|
kstat2_close(3KSTAT2), kstat2_close(3KSTAT2), kstat2_map_get(3KSTAT2), kstat2_map_get_userdata(3KSTAT2), kstat2_map_meta(3KSTAT2), kstat2_map_parent(3KSTAT2), kstat2_map_put_integer(3KSTAT2), kstat2_map_put_integers(3KSTAT2), kstat2_map_put_string(3KSTAT2), kstat2_map_put_strings(3KSTAT2), kstat2_map_remove(3KSTAT2), kstat2_map_set_data_cb(3KSTAT2), kstat2_map_set_destroy_cb(3KSTAT2), kstat2_map_set_userdata(3KSTAT2), kstat2_map_size(3KSTAT2), kstat2_map_to_array(3KSTAT2), kstat2_map_uri(3KSTAT2), kstat2_mapiter_end(3KSTAT2), kstat2_mapiter_hasnext(3KSTAT2), kstat2_mapiter_next(3KSTAT2), kstat2_mapiter_remove(3KSTAT2), kstat2_mapiter_start(3KSTAT2), kstat2_mapref_alloc(3KSTAT2), kstat2_mapref_deref(3KSTAT2), kstat2_mapref_free(3KSTAT2), kstat2_nv_meta(3KSTAT2), kstat2_open(3KSTAT2), kstat2_status_string(3KSTAT2), kstat2_update(3KSTAT2), kstat2_uri_decode(3KSTAT2), kstat2_uri_encode(3KSTAT2), libkstat2(3LIB)
The kstat2 functions are MT-Safe with the exception that only one thread may actively use a kstat2_handle_t, or any object obtained through it, at any one time. Synchronization is required if multiple threads intend to share a kstat2_handle_t or any object obtained through it. Synchronization is left to the application.