kstat2_mapref_alloc, kstat2_mapref_deref, kstat2_mapref_free - update-safe references to kstat2 maps
cc [ flag... ] file... -lkstat2 [ library...]
#include <kstat2.h>
kstat2_status_t kstat2_mapref_alloc(kstat2_map_t map,
kstat2_mapref_t *ref);
kstat2_status_t kstat2_mapref_deref(kstat2_mapref_t ref,
kstat2_map_t *map);
kstat2_status_t kstat2_mapref_free(kstat2_mapref_t *ref);
Traversing the kstat2 hierarchy to obtain a required kstat is a relatively expensive operation, so a facility to retain a reference to a map once it has been located is provided. However, when the application's kstat view is resynchronised to that of the kernel through a call to kstat2_update(), kstats that were previously present may have been deleted as a result of system configuration changes, rendering any retained kstat map references invalid. The kstat_mapref_*() functions allow safe retention of map references by allowing the application to determine if the underlying kstat has been deleted before accessing the retained reference.
The kstat2_mapref_alloc() function obtains a new reference to a kstat map.
The kstat2_mapref_deref() function dereferences the reference. If the reference is still valid, KSTAT2_S_OK will be returned and map will be set to the kstat map. If the underlying kstat has been deleted and the reference is now invalid, an error of KSTAT2_S_DEL_MAP will be returned and map will be set to NULL.
The kstat2_mapref_free() function frees a reference to a map and must be called when the application has finished with the reference, irrespective of the status of the underlying map.
On successful completion the kstat2_mapref_alloc(), kstat2_mapref_deref(), and kstat2_mapref_free() calls will return an status of KSTAT2_S_OK. On failure an error code will be returned.
The kstat2_mapref_alloc() function will fail if:
The map or ref parameters are invalid
If memory for the reference could not be allocated
The kstat_mapref_deref() function will fail if:
If the map has been deleted
The map or ref parameters are invalid
The kstat2_mapref_free() function will fail if:
If the map reference is invalid
kernel statistics driver
header
See the kstat2(3KSTAT2) manpage.
See attributes(7) for descriptions of the following attributes:
|
kstat2(3KSTAT2), 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_tree_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_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.