1 /*
2  * SPDX-FileCopyrightText: 2022 Espressif Systems (Shanghai) CO LTD
3  *
4  * SPDX-License-Identifier: Apache-2.0
5  */
6 
7 #ifndef _PKT_LIST_H_
8 #define _PKT_LIST_H_
9 
10 #include "sys/queue.h"
11 #include <stdint.h>
12 #include <stdbool.h>
13 
14 #ifdef __cplusplus
15 extern "C" {
16 #endif
17 
18 struct pkt_queue;
19 
20 typedef struct pkt_linked_item {
21     STAILQ_ENTRY(pkt_linked_item) next;
22     uint8_t data[];
23 } pkt_linked_item_t;
24 
25 #define BT_PKT_LINKED_HDR_SIZE (sizeof (pkt_linked_item_t))
26 
27 typedef void (*pkt_queue_free_cb)(pkt_linked_item_t *item);
28 
29 /*
30  * brief: create a pkt_queue instance. pkt_queue is a wrapper class of a FIFO implemented by single linked list.
31  *        The enqueue and dequeue operations of the FIFO are protected against race conditions of multiple tasks
32  * return: NULL if not enough memory, otherwise a valid pointer
33  */
34 struct pkt_queue *pkt_queue_create(void);
35 
36 /*
37  * brief: enqueue one item to the FIFO
38  * param queue: pkt_queue instance created using pkt_queue_create
39  * param item: the item to be enqueued to the FIFO
40  * return: true if enqueued successfully, false when the arguments passed in are invalid
41  */
42 bool pkt_queue_enqueue(struct pkt_queue *queue, pkt_linked_item_t *item);
43 
44 /*
45  * brief: dequeue one item for the FIFO
46  * param queue: pkt_queue instance created using pkt_queue_create
47  * return: pointer of type pkt_linked_item_t dequeued, NULL if the queue is empty or upon exception
48  */
49 pkt_linked_item_t *pkt_queue_dequeue(struct pkt_queue *queue);
50 
51 /*
52  * brief: get the pointer of the first item from the FIFO but not get it dequeued
53  * param queue: pkt_queue instance created using pkt_queue_create
54  * return: pointer of the first item in the FIFO, NULL if the FIFO is empty
55  */
56 pkt_linked_item_t *pkt_queue_try_peek_first(struct pkt_queue *queue);
57 
58 /*
59  * brief: retrieve the number of items existing in the FIFO
60  * param queue: pkt_queue instance created using pkt_queue_create
61  * return: total number of items in the FIFO
62  */
63 size_t pkt_queue_length(const struct pkt_queue *queue);
64 
65 /*
66  * brief: retrieve the status whether the FIFO is empty
67  * param queue: pkt_queue instance created using pkt_queue_create
68  * return: false if the FIFO is not empty, otherwise true
69  */
70 bool pkt_queue_is_empty(const struct pkt_queue *queue);
71 
72 /*
73  * brief: delete the item in the FIFO one by one
74  * param free_cb: destructor function for each item in the FIFO, if set to NULL, will use osi_free_func by default
75  */
76 void pkt_queue_flush(struct pkt_queue *queue, pkt_queue_free_cb free_cb);
77 
78 /*
79  * brief: delete the items in the FIFO and then destroy the pkt_queue instance.
80  * param free_cb: destructor function for each item in the FIFO, if set to NULL, will use osi_free_func by default
81  */
82 void pkt_queue_destroy(struct pkt_queue *queue, pkt_queue_free_cb free_cb);
83 
84 #ifdef __cplusplus
85 }
86 #endif
87 
88 #endif
89