| 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_NOCOPYTHMAP_SETROOTthmap_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.1 |