From 6453a1c311478def7c3dad0c1c2e2e455c309464 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Igor=20Mi=C5=A1i=C4=87?= Date: Thu, 4 May 2023 15:25:46 +0200 Subject: [PATCH] datamanClient: add Doxygen documentation for the API. --- src/lib/dataman_client/DatamanClient.hpp | 172 ++++++++++++++++++++++- 1 file changed, 170 insertions(+), 2 deletions(-) diff --git a/src/lib/dataman_client/DatamanClient.hpp b/src/lib/dataman_client/DatamanClient.hpp index 8d28097b10..a777684895 100644 --- a/src/lib/dataman_client/DatamanClient.hpp +++ b/src/lib/dataman_client/DatamanClient.hpp @@ -51,20 +51,142 @@ public: DatamanClient(const DatamanClient &) = delete; DatamanClient &operator=(const DatamanClient &) = delete; + /** + * @brief Reads data synchronously from the dataman for the specified item and index. + * + * @param[in] item The item to read data from. + * @param[in] index The index of the item to read data from. + * @param[out] buffer Pointer to the buffer to store the read data. + * @param[in] length The length of the data to read. + * @param[in] timeout The timeout in microseconds for waiting for the response. + * + * @return true if data was read successfully within the timeout, false otherwise. + */ bool readSync(dm_item_t item, uint32_t index, uint8_t *buffer, uint32_t length, hrt_abstime timeout = 1000_ms); + + /** + * @brief Write data to the dataman synchronously. + * + * @param[in] item The data item type to write. + * @param[in] index The index of the data item. + * @param[in] buffer The buffer that contains the data to write. + * @param[in] length The length of the data to write. + * @param[in] timeout The maximum time in microseconds to wait for the response. + * + * @return True if the write operation succeeded, false otherwise. + */ bool writeSync(dm_item_t item, uint32_t index, uint8_t *buffer, uint32_t length, hrt_abstime timeout = 1000_ms); + + /** + * @brief Clears the data in the specified dataman item. + * + * @param[in] item The dataman item to clear. + * @param[in] timeout The timeout for the operation. + * + * @return True if the operation was successful, false otherwise. + */ bool clearSync(dm_item_t item, hrt_abstime timeout = 1000_ms); + + /** + * @brief Locks an item in the dataman for exclusive access. + * + * This function sends a DM_LOCK request to the dataman to lock an item for exclusive access. + * If the item is already locked, it will wait and retry until it can obtain the lock or the timeout + * is reached. Once the lock is obtained, the item can be safely modified. + * + * @param[in] item The item to be locked. + * @param[in] timeout The maximum time to wait for the lock in microseconds. + * @return true if the item is locked successfully, false otherwise. + */ bool lockSync(dm_item_t item, hrt_abstime timeout = 1000_ms); + + /** + * Unlock an item in dataman. + * + * @param[in] item: The item to unlock. + * @param[in] timeout: The timeout for the operation. + * @return True if the unlock operation was successful, false otherwise. + */ bool unlockSync(dm_item_t item, hrt_abstime timeout = 1000_ms); + /** + * @brief Initiates an asynchronous request to read the data from dataman for a specific item and index. + * + * @param[in] item The item to read from. + * @param[in] index The index within the item to read from. + * @param[out] buffer The buffer to store the read data in. + * @param[in] length The length of the data to read. + * + * @return True if the read request was successfully queued, false otherwise. + * + * @note The buffer must be kept alive as long as the request did not finish. + * The completion status of the request can be obtained with the + * lastOperationCompleted() function. + */ bool readAsync(dm_item_t item, uint32_t index, uint8_t *buffer, uint32_t length); + + /** + * @brief Initiates an asynchronous request to write the data to dataman for a specific item and index. + * + * @param[in] item The item to write data to. + * @param[in] index The index of the item to write data to. + * @param[in] buffer The buffer containing the data to write. + * @param[in] length The length of the data to write. + * + * @return True if the write request was successfully sent, false otherwise. + * + * @note The buffer must be kept alive as long as the request did not finish. + * The completion status of the request can be obtained with the + * lastOperationCompleted() function. + */ bool writeAsync(dm_item_t item, uint32_t index, uint8_t *buffer, uint32_t length); + + /** + * @brief Initiates an asynchronous request to clear an item in dataman. + * + * The request is only initiated if the DatamanClient is in the Idle state. + * + * @param[in] item The item to clear. + * @return True if the request was successfully initiated, false otherwise. + */ bool clearAsync(dm_item_t item); + + /** + * @brief Locks a dataman item asynchronously. + * + * This function sends a lock request to the dataman service, asking it to lock the specified item. + * The function returns immediately, without waiting for the lock operation to complete. + * + * @param[in] item The dataman item to be locked. + * @return True if the lock request was successfully sent, false otherwise. + */ bool lockAsync(dm_item_t item); + + /** + * @brief Unlocks the specified dataman item asynchronously. + * + * @param[in] item The item to unlock. + * @return true if the request was successfully queued, false otherwise. + */ bool unlockAsync(dm_item_t item); + /** + * @brief Updates the state of the dataman client for asynchronous functions. + * + * This function shall be called regularly. It checks if there is any response from the dataman, + * and updates the state accordingly. If there is no response for a request, it retries the + * request after a timeout. + * + * @see readAsync(), writeAsync(), clearAsync(), lockAsync(), unlockAsync(), lastOperationCompleted() + */ void update(); + /** + * @brief Check if the last dataman operation has completed and whether it was successful. + * + * @param[out] success Output parameter indicating whether the last operation was successful. + * @return true if the last operation has completed, false otherwise. + */ bool lastOperationCompleted(bool &success); /** @@ -114,14 +236,55 @@ public: DatamanCache(const char *cache_miss_perf_counter_name, uint32_t num_items); ~DatamanCache(); + /** + * @brief Resizes the cache to hold the specified number of items. + * + * @param[in] num_items The number of items the cache should hold. + */ void resize(uint32_t num_items); + /** + * @brief Invalidates all cached items in the cache by resetting their cache_state to Idle. + */ void invalidate(); + /** + * @brief Adds an index for items to be cached. + * + * Calling this function will exit immediately. Data shall be acquired with 'update()' function and + * it will be cached at full size. Later it can be retrieved with 'loadWait()' function. + * + * @param[in] item The item to load. + * @param[in] index The index of the item to load. + * + * @return true if the item was added to be cached, false otherwise if the size of the cache is reached. + */ bool load(dm_item_t item, uint32_t index); + /** + * @brief Loads for a specific item from the cache or acquires and wait for it if not found in the cache. + * + * @param[in] item Dataman item type + * @param[in] index Item index + * @param[out] buffer Buffer for the data to be stored + * @param[in] length Length of the buffer in bytes to be stored + * @param[in] timeout Maximum time to wait for the item to be available in microseconds, 0 to return immediately + * + * @return true if item was successfully loaded from cache or acquired through the client, false otherwise. + * + * @note This function will block if timeout is set differently than 0 and data doesn't exist in cache. + */ bool loadWait(dm_item_t item, uint32_t index, uint8_t *buffer, uint32_t length, hrt_abstime timeout = 0); + /** + * @brief Updates the dataman cache by checking for responses from the DatamanClient and processing them. + * + * If there are items in the cache, this function will call the DatamanClient's 'update()' function to check for responses. + * Depending on the state of each item, it will either send a request, wait for a response, or report an error. + * If a response is received for an item, it will be marked as "response received" and the update index will be changed + * to the next item in the cache. This function does not block and returns immediately. + * The data can be acquired with the 'loadWait()' function after it has been cached. + */ void update(); /** @@ -129,8 +292,13 @@ public: * * @return true if there are items to be processed. */ - bool isLoading() {return (_item_counter > 0);} + bool isLoading() { return (_item_counter > 0); } + /** + * @brief Returns a reference to the DatamanClient instance used by the DatamanCache. + * + * @return A reference to the DatamanClient instance used by the DatamanCache. + */ DatamanClient &client() { return _client; } int size() const { return _num_items; } @@ -156,7 +324,7 @@ private: uint32_t _load_index{0}; ///< index for tracking last index used by load function uint32_t _update_index{0}; ///< index for tracking last index used by update function uint32_t _item_counter{0}; ///< number of items to process with update function - uint32_t _num_items{0}; + uint32_t _num_items{0}; ///< number of items that cache can store DatamanClient _client{};