From 2b5bfae00f40e779374f8c4670a8ae9c1fe75d9c Mon Sep 17 00:00:00 2001 From: Sergei Shirokov Date: Thu, 5 Dec 2024 15:09:22 +0200 Subject: [PATCH] more docs; previous pr review fixes --- libcanard/canard.c | 27 ++++++++++++++++----------- libcanard/canard.h | 12 +++++++++--- 2 files changed, 25 insertions(+), 14 deletions(-) diff --git a/libcanard/canard.c b/libcanard/canard.c index 3ec49d9..aff91b3 100644 --- a/libcanard/canard.c +++ b/libcanard/canard.c @@ -597,11 +597,11 @@ CANARD_PRIVATE void txPopAndFreeTransfer(struct CanardTxQueue* const que, struct CanardTxQueueItem* const tx_item, const bool drop_whole_transfer) { - struct CanardTxQueueItem* curr_tx_item = tx_item; - struct CanardTxQueueItem* tx_item_to_free = NULL; - while (NULL != (tx_item_to_free = canardTxPop(que, curr_tx_item))) + struct CanardTxQueueItem* next_tx_item = tx_item; + struct CanardTxQueueItem* tx_item_to_free = canardTxPop(que, next_tx_item); + while (NULL != tx_item_to_free) { - curr_tx_item = tx_item_to_free->next_in_transfer; + next_tx_item = tx_item_to_free->next_in_transfer; canardTxFree(que, ins, tx_item_to_free); if (!drop_whole_transfer) @@ -609,6 +609,8 @@ CANARD_PRIVATE void txPopAndFreeTransfer(struct CanardTxQueue* const que, break; } que->stats.dropped_frames++; + + tx_item_to_free = canardTxPop(que, next_tx_item); } } @@ -617,11 +619,11 @@ CANARD_PRIVATE void txFlushExpiredTransfers(struct CanardTxQueue* const q const struct CanardInstance* const ins, const CanardMicrosecond now_usec) { - struct CanardTxQueueItem* tx_item = NULL; - while (NULL != (tx_item = MUTABLE_CONTAINER_OF( // - struct CanardTxQueueItem, - cavlFindExtremum(que->deadline_root, false), - deadline_base))) + struct CanardTxQueueItem* tx_item = MUTABLE_CONTAINER_OF( // + struct CanardTxQueueItem, + cavlFindExtremum(que->deadline_root, false), + deadline_base); + while (NULL != tx_item) { if (now_usec <= tx_item->tx_deadline_usec) { @@ -631,6 +633,11 @@ CANARD_PRIVATE void txFlushExpiredTransfers(struct CanardTxQueue* const q // All frames of the transfer are dropped at once b/c they all have the same deadline. txPopAndFreeTransfer(que, ins, tx_item, true); // drop the whole transfer + + tx_item = MUTABLE_CONTAINER_OF( // + struct CanardTxQueueItem, + cavlFindExtremum(que->deadline_root, false), + deadline_base); } } @@ -1213,8 +1220,6 @@ struct CanardTxQueueItem* canardTxPeek(const struct CanardTxQueue* const que) struct CanardTxQueueItem* out = NULL; if (que != NULL) { - // Paragraph 6.7.2.1.15 of the C standard says: - // A pointer to a structure object, suitably converted, points to its initial member, and vice versa. struct CanardTreeNode* const priority_node = cavlFindExtremum(que->priority_root, false); out = MUTABLE_CONTAINER_OF(struct CanardTxQueueItem, priority_node, priority_base); } diff --git a/libcanard/canard.h b/libcanard/canard.h index 905e74e..726d656 100644 --- a/libcanard/canard.h +++ b/libcanard/canard.h @@ -322,7 +322,7 @@ struct CanardTxQueueStats /// @param frame The mutable frame that is being handled. /// @return The result of the handling operation: /// - Any positive value: the frame was successfully handled. -/// This indicates that the frame payload was accepted (and its ownership could be potentially moved, +/// This indicates that the frame payload was accepted (and its payload ownership could be potentially moved, /// see `canardTxPeek` for the details), and the frame can be safely removed from the queue. /// - Zero: the frame was not handled, and so the frame should be kept in the queue. /// It will be retried on some future `canardTxPoll()` call according to the queue state in the future. @@ -546,6 +546,11 @@ struct CanardTxQueue canardTxInit(const size_t capacity, /// be dropped (incrementing `CanardTxQueueStats::dropped_frames` field per such a frame). /// If this timeout behavior is not needed, the timestamp value can be set to zero. /// +/// The described above automatic dropping of timed-out frames was added in the v4 of the library as an optional +/// feature. It is applied only to the frames that are already in the TX queue (not the new ones that are being pushed +/// in this call). The feature can be disabled by passing zero time in the `now_usec` parameter, +/// so that it will be up to the application to track the `tx_deadline_usec` (see `canardTxPeek`). +/// /// The function returns the number of frames enqueued into the prioritized TX queue (which is always a positive /// number) in case of success (so that the application can track the number of items in the TX queue if necessary). /// In case of failure, the function returns a negated error code: either invalid argument or out-of-memory. @@ -590,8 +595,8 @@ int32_t canardTxPush(struct CanardTxQueue* const que, /// /// The timestamp values of returned frames are initialized with tx_deadline_usec from canardTxPush(). /// Timestamps are used to specify the transmission deadline. It is up to the application and/or the media layer -/// to implement the discardment of timed-out transport frames. The library does not check it, so a frame that is -/// already timed out may be returned here. +/// to implement the discardment of timed-out transport frames. The library does not check it in this call, +/// so a frame that is already timed out may be returned here. /// /// If the queue is empty or if the argument is NULL, the returned value is NULL. /// @@ -650,6 +655,7 @@ void canardTxFree(struct CanardTxQueue* const que, /// @param que The TX queue to poll. /// @param ins The Canard instance. /// @param now_usec The current time in microseconds. It is used to determine if the frame has timed out. +/// Use zero value to disable automatic dropping of timed-out frames. /// @param user_reference The user reference to be passed to the frame handler. /// @param frame_handler The frame handler function that will be called to transmit the frame. /// @return Zero if the queue is empty or there is no frame handler (NULL).