Function rosidl_runtime_c_type_description_utils_get_necessary_referenced_type_descriptions_map

• Defined in File type_description_utils.h

Function Documentation

rcutils_ret_t rosidl_runtime_c_type_description_utils_get_necessary_referenced_type_descriptions_map(const rosidl_runtime_c__type_description__IndividualTypeDescription *main_type_description, const rcutils_hash_map_t *referenced_types_map, const rcutils_allocator_t *allocator, rcutils_hash_map_t **seen_map)

Return a map of only the referenced type descriptions that are recursively necessary.

The seen_map output arg must be passed in pointing to NULL. It’s a parameter so it can be passed into subsequent recursive calls to traverse nested types.

A referenced type description is recursively necessary if it is either:

• Needed by a field of the main IndividualTypeDescription

• Needed by a field of any prior necessary referenced type descriptions (hence recursive)

For more clarity, an unnecessary referenced type description will not be referenced when parsing a TypeDescription, and hence can be excluded.

Ownership:

• The caller assumes ownership of the output rcutils_hash_map_t and must free it and its elements, but NOT finalize its values.

• The output rcutils_hash_map_t has values that borrows the referenced_types_map arg’s IndividualTypeDescription values. It is not authorized to deallocate them and it cannot outlive owner it borrows from.

  • Finalizing the output rcutils_hash_map_t should not result in its values getting finalized.

Procedure:

1. Create seen map

2. [Iterate through fields]:

   1. If field is not nested type or field’s nested type is seen in the seen map:

      • Continue

   2. If nested type is missing in referenced types or nested type name is empty:

      • Throw error

   3. Else:

      • Add to seen map

      • Recurse on referenced type

3. Output seen map

Attribute	Adherence
Allocates Memory	Yes
Thread-Safe	No
Uses Atomics	No
Lock-Free	Yes

Parameters:

• main_type_description – [in] the main individual type description to check the fields of

• referenced_types_map – [in] a map of referenced IndividualTypeDescription objects from the main individual type description’s parent TypeDescription object, keyed by their type names.

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

• seen_map – [inout] rcutils_hash_map_t of seen necessary IndividualTypeDescription objects keyed by their type names. Used in recursive calls. Must point to NULL for user’s top level call, outputs pointing to NULL if error.

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_NOT_FOUND if passed referenced types are missing necessary types, or

Returns:

#RCUTILS_RET_ERROR if an unknown error occurs.