This file defines the data structure for a hash, which is an unordered list of elements, where each element contains a key (char string) and a pointer to another hash. More...

Data Structures
struct	kvtree

struct	kvtree_elem

Functions
int	kvtree_read_scatter_single (const char prefix, kvtree data)

Allocate and delete hash objects
kvtree *	kvtree_new (void)

int	kvtree_delete (kvtree **ptr_hash)

size, get, set, unset, and merge functions
int	kvtree_size (const kvtree *hash)

kvtree *	kvtree_get (const kvtree hash, const char key)

kvtree *	kvtree_set (kvtree hash, const char key, kvtree *hash_value)

kvtree *	kvtree_extract (kvtree hash, const char key)

int	kvtree_unset (kvtree hash, const char key)

int	kvtree_unset_all (kvtree *hash)

int	kvtree_merge (kvtree hash1, const kvtree hash2)

kvtree *	kvtree_setf (kvtree hash, kvtree hash_value, const char *format,...)

kvtree *	kvtree_getf (const kvtree hash, const char format,...)

int	kvtree_sort (kvtree *hash, int direction)

int	kvtree_sort_int (kvtree *hash, int direction)

int	kvtree_list_int (const kvtree hash, int num, int **list)

get, set, and unset hashes using a key/value pair
kvtree *	kvtree_set_kv (kvtree hash, const char key, const char *val)

kvtree *	kvtree_set_kv_int (kvtree hash, const char key, int val)

kvtree *	kvtree_get_kv (const kvtree hash, const char key, const char *val)

kvtree *	kvtree_get_kv_int (const kvtree hash, const char key, int val)

int	kvtree_unset_kv (kvtree hash, const char key, const char *val)

int	kvtree_unset_kv_int (kvtree hash, const char key, int val)

Hash element functions
kvtree_elem *	kvtree_elem_first (const kvtree *hash)

kvtree_elem *	kvtree_elem_next (const kvtree_elem *elem)

char *	kvtree_elem_key (const kvtree_elem *elem)

int	kvtree_elem_key_int (const kvtree_elem *elem)

kvtree *	kvtree_elem_hash (const kvtree_elem *elem)

kvtree_elem *	kvtree_elem_get (const kvtree hash, const char key)

char *	kvtree_elem_get_first_val (const kvtree hash, const char key)

kvtree_elem *	kvtree_elem_extract (kvtree hash, const char key)

kvtree_elem *	kvtree_elem_extract_int (kvtree *hash, int key)

kvtree_elem *	kvtree_elem_extract_by_addr (kvtree hash, kvtree_elem elem)

char *	kvtree_get_val (const kvtree hash, const char key)

Pack and unpack hash and elements into a char buffer
size_t	kvtree_pack_size (const kvtree *hash)

size_t	kvtree_pack (char buf, const kvtree hash)

size_t	kvtree_unpack (const char buf, kvtree hash)

Read and write hash to a file
int	kvtree_write_persist (void *ptr_buf, size_t ptr_size, const kvtree *hash)

ssize_t	kvtree_write_fd (const char file, int fd, const kvtree hash)

ssize_t	kvtree_read_fd (const char file, int fd, kvtree hash)

int	kvtree_write_file (const char file, const kvtree hash)

int	kvtree_read_file (const char file, kvtree hash)

int	kvtree_read_with_lock (const char file, kvtree hash)

int	kvtree_write_with_lock (const char file, kvtree hash)

int	kvtree_lock_open_read (const char file, int fd, kvtree *hash)

int	kvtree_write_close_unlock (const char file, int fd, const kvtree *hash)

int	kvtree_write_to_gather (const char prefix, kvtree data, int ranks)

Print hash and elements to stdout for debugging
int	kvtree_print (const kvtree *hash, int indent)

int	kvtree_print_mode (const kvtree *hash, int indent, int mode)

int	kvtree_log (const kvtree *hash, int log_level, int indent)

Function Documentation

◆ kvtree_delete()

int kvtree_delete ( kvtree ** ptr_hash )

frees a hash

◆ kvtree_elem_extract()

kvtree_elem* kvtree_elem_extract	(	kvtree *	hash,
		const char *	key
	)

given a hash and a key, find first matching element, remove it from the hash, and return it

◆ kvtree_elem_extract_by_addr()

kvtree_elem* kvtree_elem_extract_by_addr	(	kvtree *	hash,
		kvtree_elem *	elem
	)

extract element from hash given the hash and the address of the element

◆ kvtree_elem_extract_int()

kvtree_elem* kvtree_elem_extract_int	(	kvtree *	hash,
		int	key
	)

given a hash and a key, find first matching element, remove it from the hash, and return it

◆ kvtree_elem_first()

kvtree_elem* kvtree_elem_first ( const kvtree * hash )

returns the first element for a given hash

◆ kvtree_elem_get()

kvtree_elem* kvtree_elem_get	(	const kvtree *	hash,
		const char *	key
	)

given a hash and a key, find first matching element and return its address, returns NULL if not found

◆ kvtree_elem_get_first_val()

char* kvtree_elem_get_first_val	(	const kvtree *	hash,
		const char *	key
	)

given a hash and a key, return a pointer to the key of the first element of that key's hash

◆ kvtree_elem_hash()

kvtree* kvtree_elem_hash ( const kvtree_elem * elem )

returns a pointer to the hash of the specified element

◆ kvtree_elem_key()

char* kvtree_elem_key ( const kvtree_elem * elem )

returns a pointer to the key of the specified element

◆ kvtree_elem_key_int()

int kvtree_elem_key_int ( const kvtree_elem * elem )

same as kvtree_elem_key, but converts the key as an int (returns 0 if key is not defined)

◆ kvtree_elem_next()

kvtree_elem* kvtree_elem_next ( const kvtree_elem * elem )

given a hash element, returns the next element

◆ kvtree_extract()

kvtree* kvtree_extract	(	kvtree *	hash,
		const char *	key
	)

given a hash and a key, extract and return hash for specified key, returns NULL if not found

◆ kvtree_get()

kvtree* kvtree_get	(	const kvtree *	hash,
		const char *	key
	)

given a hash and a key, return the hash associated with key, returns NULL if not found

◆ kvtree_get_kv()

kvtree* kvtree_get_kv	(	const kvtree *	hash,
		const char *	key,
		const char *	val
	)

shortcut to get hash assocated with the subkey of a key in a hash with one call

◆ kvtree_get_kv_int()

kvtree* kvtree_get_kv_int	(	const kvtree *	hash,
		const char *	key,
		int	val
	)

same as kvtree_get_kv, but with the subkey specified as an int

◆ kvtree_get_val()

char* kvtree_get_val	(	const kvtree *	hash,
		const char *	key
	)

◆ kvtree_getf()

kvtree* kvtree_getf	(	const kvtree *	hash,
		const char *	format,
			...
	)

same as above, but simply returns the hash associated with the list of keys

◆ kvtree_list_int()

int kvtree_list_int	(	const kvtree *	hash,
		int *	num,
		int **	list
	)

return list of keys in hash as integers, caller must free list

◆ kvtree_lock_open_read()

int kvtree_lock_open_read	(	const char *	file,
		int *	fd,
		kvtree *	hash
	)

given a filename and hash, lock the file, open it, and read it into hash, set fd to the opened file descriptor. Note that this function actually acquires a write lock, not a read lock, allowing you do a read-modify-write before you unlock it.

◆ kvtree_log()

int kvtree_log	(	const kvtree *	hash,
		int	log_level,
		int	indent
	)

logs specified hash for debugging

◆ kvtree_merge()

int kvtree_merge	(	kvtree *	hash1,
		const kvtree *	hash2
	)

merges (copies) elements from hash2 into hash1

◆ kvtree_new()

kvtree* kvtree_new ( void )

allocates a new hash

◆ kvtree_pack()

size_t kvtree_pack	(	char *	buf,
		const kvtree *	hash
	)

packs the given hash into specified buf and returns the number of bytes written

◆ kvtree_pack_size()

size_t kvtree_pack_size ( const kvtree * hash )

computes the number of bytes needed to pack the given hash

◆ kvtree_print()

int kvtree_print	(	const kvtree *	hash,
		int	indent
	)

prints specified hash to stdout for debugging

◆ kvtree_print_mode()

int kvtree_print_mode	(	const kvtree *	hash,
		int	indent,
		int	mode
	)

prints specified hash to stdout for debugging

◆ kvtree_read_fd()

ssize_t kvtree_read_fd	(	const char *	file,
		int	fd,
		kvtree *	hash
	)

executes logic of kvtree_read using an opened file descriptor

◆ kvtree_read_file()

int kvtree_read_file	(	const char *	file,
		kvtree *	hash
	)

opens specified file and reads in a hash storing its contents in the given hash object

◆ kvtree_read_scatter_single()

int kvtree_read_scatter_single	(	const char *	prefix,
		kvtree *	data
	)

◆ kvtree_read_with_lock()

int kvtree_read_with_lock	(	const char *	file,
		kvtree *	hash
	)

given a filename and hash, lock/open/read/close/unlock the file storing its contents in the hash

◆ kvtree_set()

kvtree* kvtree_set	(	kvtree *	hash,
		const char *	key,
		kvtree *	hash_value
	)

given a hash, a key, and a hash value, set (or reset) the key's hash

◆ kvtree_set_kv()

kvtree* kvtree_set_kv	(	kvtree *	hash,
		const char *	key,
		const char *	val
	)

shortcut to create a key and subkey in a hash with one call

◆ kvtree_set_kv_int()

kvtree* kvtree_set_kv_int	(	kvtree *	hash,
		const char *	key,
		int	val
	)

same as kvtree_set_kv, but with the subkey specified as an int

◆ kvtree_setf()

kvtree* kvtree_setf	(	kvtree *	hash,
		kvtree *	hash_value,
		const char *	format,
			...
	)

traverse the given hash using a printf-like format string setting an arbitrary list of keys to set (or reset) the hash associated with the last key

◆ kvtree_size()

int kvtree_size ( const kvtree * hash )

return size of hash (number of keys)

◆ kvtree_sort()

int kvtree_sort	(	kvtree *	hash,
		int	direction
	)

sort the hash assuming the keys are strings

◆ kvtree_sort_int()

int kvtree_sort_int	(	kvtree *	hash,
		int	direction
	)

sort the hash assuming the keys are ints

◆ kvtree_unpack()

size_t kvtree_unpack	(	const char *	buf,
		kvtree *	hash
	)

unpacks hash from specified buffer into given hash object and returns the number of bytes read

◆ kvtree_unset()

int kvtree_unset	(	kvtree *	hash,
		const char *	key
	)

given a hash and a key, extract and delete any matching element

◆ kvtree_unset_all()

int kvtree_unset_all ( kvtree * hash )

unset all values in the hash, but don't delete it

◆ kvtree_unset_kv()

int kvtree_unset_kv	(	kvtree *	hash,
		const char *	key,
		const char *	val
	)

unset subkey under key, and if that removes the only element for key, unset key as well

◆ kvtree_unset_kv_int()

int kvtree_unset_kv_int	(	kvtree *	hash,
		const char *	key,
		int	val
	)

same as kvtree_unset_kv, but with the subkey specified as an int

◆ kvtree_write_close_unlock()

int kvtree_write_close_unlock	(	const char *	file,
		int *	fd,
		const kvtree *	hash
	)

given a filename, an opened file descriptor, and a hash, overwrite file with hash, close, and unlock file

◆ kvtree_write_fd()

ssize_t kvtree_write_fd	(	const char *	file,
		int	fd,
		const kvtree *	hash
	)

executes logic of kvtree_has_write with opened file descriptor

◆ kvtree_write_file()

int kvtree_write_file	(	const char *	file,
		const kvtree *	hash
	)

write the given hash to specified file

◆ kvtree_write_persist()

int kvtree_write_persist	(	void **	ptr_buf,
		size_t *	ptr_size,
		const kvtree *	hash
	)

persist hash in newly allocated buffer, return buffer address and size to be freed by caller

◆ kvtree_write_to_gather()

int kvtree_write_to_gather	(	const char *	prefix,
		kvtree *	data,
		int	ranks
	)

write kvtree as gather/scatter file, input kvtree must be in form:

0
  <kvtree_for_rank_0>
1
  <kvtree_for_rank_1>

requires exactly one entry for each rank starting at 0 couting up to ranks-1 items in kvtree do not need to be sorted before the call

◆ kvtree_write_with_lock()

int kvtree_write_with_lock	(	const char *	file,
		kvtree *	hash
	)