diff options
Diffstat (limited to 'refarray/ref_array.h')
| -rw-r--r-- | refarray/ref_array.h | 158 |
1 files changed, 140 insertions, 18 deletions
diff --git a/refarray/ref_array.h b/refarray/ref_array.h index 4211290..004c460 100644 --- a/refarray/ref_array.h +++ b/refarray/ref_array.h @@ -29,56 +29,178 @@ struct ref_array; #define EOK 0 #endif -/*************************************/ -/* Interface to the referenced array */ -/*************************************/ +/** @mainpage The Referenced Array Interface + * + * The referenced array interface is a dynamically allocated + * array of data of any type. The array can be shared by + * multiple objects to avoid data duplication. + * + * The array is created once and then any number of + * the references can be requested. The references are pointers + * to the array. Each reference must be freed after use. + * Freeing last reference to the array would free the array's storage. + * + * The array does not have any knowledge of the data type + * of the actual data stored in the array. All elements of the array + * are of the same size as prescribed by caller when the array is created. + * The caller can potentially mix different types of data in the array + * but this should be done with caution. + * + * At the moment the interface is not complete. + * It provides basic functionality required to support other + * components. In future it might make sense to add entry points + * to insert and delete elements from the array. + * Current use cases do not require this kind of + * functionality so it is left out of the implementation. + * + */ + +/** + * @defgroup ref_array Interface + * @{ + */ +/** + * @brief Enumeration of the delete modes + * + * When the array is destroyed each element of the array + * most likely needs to be freed. Same is true when an element + * is removed from the array. However the caller might need + * to do different things with the data depending on whether + * the array is destroyed or whether the element is removed. + * This enumeration defines constants that you used to indicate + * which operation was performed. + */ typedef enum { REF_ARRAY_DESTROY, REF_ARRAY_DELETE, } ref_array_del_enum; -/* Callback that can be provided by caller - * to free data when the storage is actually destroyed +/** + * @brief Element cleanup callback + * + * Callback that can be provided by a caller + * to free data when the storage is actually destroyed. */ typedef void (*ref_array_fn)(void *elem, ref_array_del_enum type, void *data); -/* Create referenced array */ +/** + * @brief Create referenced array + * + * @param[out] ra Newly created array object. + * @param[in] elem Element size in bytes. + * @param[in] grow_by Defines how many elements + * should be allocated together + * as one chunk. + * @param[in] cb Cleanup callback. + * @param[in] data Caller supplied data + * passed to cleanup callback. + * + * @return 0 - Success. + * @return ENOMEM - No memory. + * @return EINVAL - Invalid argument. + */ int ref_array_create(struct ref_array **ra, size_t elem, uint32_t grow_by, ref_array_fn cb, void *data); -/* Get new reference to an array */ +/** + * @brief Get new reference to an array + * + * @param[in] ra Existing array object. + * + * @return A new reference to an array object. + * @return NULL - Invalid argument. + */ struct ref_array *ref_array_getref(struct ref_array *ra); -/* Delete the array */ +/** + * @brief Delete the array + * + * @param[in] ra Existing array object + * or a reference. + * + */ void ref_array_destroy(struct ref_array *ra); -/* Add new element to the array */ +/** + * @brief Add new element to the array + * + * Appends an element to the end of the array. + * + * @param[in] ra Existing array object. + * @param[in] element Pointer to data. + * The number of bytes + * defined at the array creation + * as the array size will be copied + * into the array element. + * + * @return 0 - Success. + * @return ENOMEM - No memory. + * @return EINVAL - Invalid argument. + */ int ref_array_append(struct ref_array *ra, void *element); -/* Get element */ +/** + * @brief Get element data + * + * Retrieves data from the array element. + * + * @param[in] ra Existing array object. + * @param[in] idx Index of the array element. + * @param[in] acptr Pointer to the memory + * where the element's data + * will be copied. Can be NULL. + * In this case nothing is copied. + * + * @return Pointer to the data stored in the element. + * Conventionally it should be a const pointer, + * however such declaration would make using + * variable that receives the result of this + * function immutable. This is very inconvenient + * because such variable should be able to + * point to data related to multiple elements + * of the array. + * + * @return Pointer to the element's data. + * @return NULL if index is out of range. + */ void *ref_array_get(struct ref_array *ra, uint32_t idx, void *acptr); -/* Get array length */ +/** + * @brief Get array length + * + * Determines length of the array. + * + * @param[in] ra Existing array object. + * @param[out] len Variable will receive + * the length of the array. + * + * @return 0 - Success. + * @return EINVAL - Invalid argument. + */ int ref_array_getlen(struct ref_array *ra, uint32_t *len); -/* Alternative function to get length. - * Returns 0 if the array is invalid +/** + * @brief Array length + * + * Alternative function to get length. + * + * @param[in] ra Existing array object. + * + * @return Length of the array. Returns 0 if the array is invalid. */ uint32_t ref_array_len(struct ref_array *ra); - -/* In future in might make sense to add entry points - * to insert and delete elements from the array. - * Current use cases do not require this kind of - * functionality so it is left out of the implementation +/** + * @} */ + #endif |