Queues

picoTCP’s queues are thread-safe, fifo structures associated to the pico_frame type. As mentioned in Packets and Frames, every frame can be part of (at most) one queue at a given time, meaning that every frame descriptor can at most belong to one specific queue. Queues are the center of the communication among modules, both protocols and drivers base their frame processing on this kind of structure. The API provided to the picoTCP module developer is the following:

• Creating a queue: just create a new instance of the pico_queue structure. All the values are initially zero, unless you want to use explicit limits.
• Adding a frame to a queue: pico_enqueue
• Fetching the first element from the queue: pico_dequeue
• Looking at the first element, but without removing it from the queue: pico_queue_peek
• Emptying a queue: pico_queue_empty

Additionally, when defining a new queue, two limits can be enforced by altering the following fields:

• max_frames - maximum number of frames that can be enqueued. Enqueue operation will fail if the limit is reached.
• max_size - maximum size in Bytes for the sum of all the previously enqueued frames. Enqueue operation will fail if the limit is below current queue size + size of frame being enqueued.

For what concerns using picoTCP in a multithreading environment, a queue can be declared as shared after its creation by explicitly calling pico_queue_protect. This will ensure that queue operations are made atomic, when for instance sharing a socket buffer with an external task.