THMAP(9) | Kernel Developer's Manual | THMAP(9) |
thmap
—
#include <thmap.h>
thmap_t *
thmap_create
(uintptr_t
baseptr, const
thmap_ops_t *ops,
unsigned flags);
void
thmap_destroy
(thmap_t
*thmap);
void *
thmap_get
(thmap_t
*thmap, const void
*key, size_t
len);
void *
thmap_put
(thmap_t
*thmap, const void
*key, size_t len,
void *val);
void *
thmap_del
(thmap_t
*thmap, const void
*key, size_t
len);
void *
thmap_stage_gc
(thmap_t
*thmap);
void
thmap_gc
(thmap_t
*thmap, void
*ref);
void
thmap_setroot
(thmap_t
*thmap, uintptr_t
root_offset);
uintptr_t
thmap_getroot
(const
thmap_t *thmap);
Delete operations (the key/data destruction) must be synchronized with the readers using some reclamation mechanism.
thmap_create
(baseptr,
ops, flags)NULL
, then
malloc(3) and
free(3) will be used as the
default operations and baseptr should be set to
zero. Currently, the supported flags are:
THMAP_NOCOPY
THMAP_SETROOT
thmap_setroot
() routine; by default, the map
is initialized and the root node is set on
thmap_create
().thmap_destroy
(thmap)thmap_get
(thmap,
key, len)NULL
if the key is not found (see the
CAVEATS section).thmap_put
(thmap,
key, len,
val)thmap_del
(thmap,
key, len)NULL
. The memory associated with
the entry is not released immediately, because in the concurrent
environment (e.g., multi-threaded application) the caller may need to
ensure it is safe to do so. It is managed using the
thmap_stage_gc
() and
thmap_gc
() routines.thmap_stage_gc
(thmap)Returns a reference which must be passed to
thmap_gc
(). Not calling the G/C function for the
returned reference would result in a memory leak.
thmap_gc
(thmap,
ref)thmap_stage_gc
().
This function must be called after the synchronization barrier which guarantees that there are no active readers referencing the staged entries.
If the map is created using the THMAP_SETROOT flag, then the following functions are applicable:
thmap_setroot
(thmap,
root_offset)thmap_ops_t::alloc
() routine.
Return 0 on success and -1 on failure (if already set).thmap_getroot
(thmap)Members of thmap_ops_t are
uintptr_t (*alloc)(size_t len); void (*free)(uintptr_t addr, size_t len);
thmap_t *kvmap; struct obj *obj; kvmap = thmap_create(0, NULL); assert(kvmap != NULL); ... obj = obj_create(); thmap_put(kvmap, "test", sizeof("test") - 1, obj); ... obj = thmap_get(kvmap, "test", sizeof("test") - 1); ... thmap_destroy(kvmap);
While the NULL
values may be inserted,
thmap_get
() and thmap_del
()
cannot indicate whether the key was not found or a key with a
NULL
value was found. If the caller needs to
indicate an "empty" value, it can use a special pointer value,
such as (void *)(uintptr_t)0x1
.
December 11, 2018 | NetBSD 10.0 |