From 82de0613d68b9d68ab465e2653892deacbed05bd Mon Sep 17 00:00:00 2001 From: Peter Hutterer Date: Thu, 30 Sep 2021 11:03:44 +1000 Subject: [PATCH] doc: document pw_map Take some parts out of the public documentation, add a lot of internal documentation to make it easier for the next person to figure out how this works. The use of static inline prevents doxygen from generating docs, put a note in to link to the header file directly. --- src/pipewire/map.h | 74 +++++++++++++++++++++++++++++++++++----------- 1 file changed, 57 insertions(+), 17 deletions(-) diff --git a/src/pipewire/map.h b/src/pipewire/map.h index 17e45ff64..fd57f7f7c 100644 --- a/src/pipewire/map.h +++ b/src/pipewire/map.h @@ -37,7 +37,25 @@ extern "C" { /** \defgroup pw_map Map * - * \brief A map that holds objects indexed by id + * \brief A map that holds pointers to objects indexed by id + * + * The map is a sparse version of the \ref pw_array "pw_array" that manages the + * indices of elements for the caller. Adding items with + * pw_map_insert_new() returns the assigned index for that item; if items + * are removed the map re-uses indices to keep the array at the minimum + * required size. + * + * \code{.c} + * struct pw_map map = PW_MAP_INIT(4); + * + * idx1 = pw_map_insert_new(&map, ptr1); + * idx2 = pw_map_insert_new(&map, ptr2); + * // the map is now [ptr1, ptr2], size 2 + * pw_map_remove(&map, idx1); + * // the map is now [, ptr2], size 2 + * pw_map_insert_new(&map, ptr3); + * // the map is now [ptr3, ptr2], size 2 + * \endcode */ /** @@ -45,25 +63,43 @@ extern "C" { * \{ */ -/** An entry in the map */ +/** \private + * An entry in the map. This is used internally only. Each element in the + * backing pw_array is a union pw_map_item. For real items, the data pointer + * points to the item. If an element has been removed, pw_map->free_list + * is the index of the most recently removed item. That item contains + * the index of the next removed item until item->next is SPA_ID_INVALID. + * + * The free list is prepended only, the last item to be removed will be the + * first item to get re-used on the next insert. + */ union pw_map_item { - uint32_t next; /**< next free index */ - void *data; /**< data of this item, must be an even address */ + uint32_t next; /* next free index */ + void *data; /* data of this item, must be an even address */ }; -/** A map */ +/** A map. This struct should be treated as opaque by the caller. */ struct pw_map { - struct pw_array items; /**< an array with the map items */ - uint32_t free_list; /**< the free items */ + struct pw_array items; /* an array with the map items */ + uint32_t free_list; /* first free index */ }; +/** \param extend the amount of bytes to grow the map with when needed */ #define PW_MAP_INIT(extend) (struct pw_map) { PW_ARRAY_INIT(extend), SPA_ID_INVALID } +/** + * Get the number of currently allocated elements in the map. + * \note pw_map_get_size() returns the currently allocated number of + * elements in the map, not the number of actually set elements. + * \return the number of available elements before the map needs to grow + */ #define pw_map_get_size(m) pw_array_get_len(&(m)->items, union pw_map_item) #define pw_map_get_item(m,id) pw_array_get_unchecked(&(m)->items,id,union pw_map_item) #define pw_map_item_is_free(item) ((item)->next & 0x1) #define pw_map_id_is_free(m,id) (pw_map_item_is_free(pw_map_get_item(m,id))) +/** \return true if the id fits within the current map size */ #define pw_map_check_id(m,id) ((id) < pw_map_get_size(m)) +/** \return true if there is a valid item at \a id */ #define pw_map_has_item(m,id) (pw_map_check_id(m,id) && !pw_map_id_is_free(m, id)) #define pw_map_lookup_unchecked(m,id) pw_map_get_item(m,id)->data @@ -84,21 +120,24 @@ static inline void pw_map_init(struct pw_map *map, size_t size, size_t extend) map->free_list = SPA_ID_INVALID; } -/** Clear a map - * \param map the map to clear +/** Clear a map and free the data storage. All previously returned ids + * must be treated as invalid. */ static inline void pw_map_clear(struct pw_map *map) { pw_array_clear(&map->items); } +/** Reset a map but keep previously allocated storage. All previously + * returned ids must be treated as invalid. + */ static inline void pw_map_reset(struct pw_map *map) { pw_array_reset(&map->items); map->free_list = SPA_ID_INVALID; } -/** Insert data in the map +/** Insert data in the map. This function causes the map to grow if required. * \param map the map to insert into * \param data the item to add * \return the id where the item was inserted or SPA_ID_INVALID when the @@ -111,7 +150,7 @@ static inline uint32_t pw_map_insert_new(struct pw_map *map, void *data) if (map->free_list != SPA_ID_INVALID) { start = (union pw_map_item *) map->items.data; - item = &start[map->free_list >> 1]; + item = &start[map->free_list >> 1]; /* lsb always 1, see pw_map_remove */ map->free_list = item->next; } else { item = (union pw_map_item *) pw_array_add(&map->items, sizeof(union pw_map_item)); @@ -124,12 +163,12 @@ static inline uint32_t pw_map_insert_new(struct pw_map *map, void *data) return id; } -/** Insert data in the map at an index - * \param map the map to inser into - * \param id the index to insert at +/** Replace the data in the map at an index. + * + * \param map the map to insert into + * \param id the index to insert at, must be less or equal to pw_map_get_size() * \param data the data to insert - * \return 0 on success, -ENOSPC value when the index is invalid or a < 0 - * errno value. + * \return 0 on success, -ENOSPC value when the index is invalid or a negative errno */ static inline int pw_map_insert_at(struct pw_map *map, uint32_t id, void *data) { @@ -162,7 +201,8 @@ static inline int pw_map_insert_at(struct pw_map *map, uint32_t id, void *data) return 0; } -/** Remove an item at index +/** Remove an item at index. The id may get re-used in the future. + * * \param map the map to remove from * \param id the index to remove */