Function rcutils_hash_map_init

Function Documentation

rcutils_ret_t rcutils_hash_map_init(rcutils_hash_map_t *hash_map, size_t initial_capacity, size_t key_size, size_t data_size, rcutils_hash_map_key_hasher_t key_hashing_func, rcutils_hash_map_key_cmp_t key_cmp_func, const rcutils_allocator_t *allocator)

Initialize a rcutils_hash_map_t, allocating space for given capacity.

This function initializes the rcutils_hash_map_t with a given initial capacity for entries. Note this does not allocate space for keys or values in the hash_map, just the arrays of pointers to the keys and values. rcutils_hash_map_set() should still be used when assigning values.

The hash_map argument should point to allocated memory and should have been zero initialized with rcutils_get_zero_initialized_hash_map().

Attribute

Adherence

Allocates Memory

Yes

Thread-Safe

No

Uses Atomics

No

Lock-Free

Yes

Example: 

rcutils_hash_map_t hash_map = rcutils_get_zero_initialized_hash_map();
rcutils_ret_t ret =
  rcutils_hash_map_init(&hash_map, 2, rcutils_get_default_allocator());
if (ret != RCUTILS_RET_OK) {
  // ... do error handling
}
// ... use the hash_map and when done:
ret = rcutils_hash_map_fini(&hash_map);
if (ret != RCUTILS_RET_OK) {
  // ... do error handling
}

Parameters:

  • hash_map – [inout] rcutils_hash_map_t to be initialized

  • initial_capacity – [in] the amount of initial capacity for the hash_map - this must be greater than zero and will be automatically rounded up to the next power of 2

  • key_size – [in] the size (in bytes) of the key used to index the data

  • data_size – [in] the size (in bytes) of the data being stored

  • key_hashing_func – [in] a function that returns a hashed value for a key

  • key_cmp_func – [in] a function used to compare keys

  • allocator – [in] the allocator to use through out the lifetime of the hash_map

Returns:

RCUTILS_RET_OK if successful, or

Returns:

RCUTILS_RET_INVALID_ARGUMENT for invalid arguments, or

Returns:

RCUTILS_RET_BAD_ALLOC if memory allocation fails, or

Returns:

RCUTILS_RET_STRING_MAP_ALREADY_INIT if alread initialized, or

Returns:

RCUTILS_RET_ERROR if an unknown error occurs.