The Map Utility

This document is part of the online Horus Documentation, under Horus Utilities.

--MUTS provides a utility that maps fixed size keys to structures, somewhat like a data base. Currently, this is implemented through a hash table. This utility allows you to create maps, create records with keys, look up these records, and loop through all records in a map.

SOURCES

include/muts/map.h
src/util/map.c

INCLUDE

#include "muts.h"
#include "muts/map.h"

INTERFACE

error_t map_create(
	struct mem_chan *mem,
	int record_size,
	int key_size,
	map_id *pmap
);

Create a map, and return a descriptor of type map_id. This descriptor has to be presented to each further access to the map.

void *map_lookup(
	map_id map,
	void *key,
	unsigned int options
);

Lookup a record. If the MAP_CREATE option is set, the record is created when unavailable. A new record is zeroed except for the key. If not and unavailable, null is returned.

void map_delete(
	map_id map,
	void *key
);

Delete the given record.

void map_foreach(
	map_id map,
	void (*func)(void *, void *),
	void *
);

Invoke the given function for all entries in the map. Depending on the storage strategy (see below), this may be in sorted order. The function is invoked with the given parameter and a pointer to the record.

void map_release(map_id map);

Release the entire map.

EXAMPLE

struct record {
	struct key key;
	struct data data;
};

extern struct mem_chan *mem;
extern struct key key;
map_id map;
struct record *record;

map_create(mem, sizeof(*record), sizeof(key), &map);
record = map_lookup(map, &key, MAP_CREATE);
map_delete(map, &key);
map_destroy(map, 0);

FUTURE WORK

It will be possible to specify storage strategies. E.g., something like map_hash(&map, HASH_SIZE) or map_binary(&map) or etc.. Currently, however, a fixed hash table is built in.

This document is part of the online Horus Documentation.