src_frescan/frescan_queues.h

   1 /*!
   2  * @file frescan_queues.h
   3  *
   4  * @brief FRESCAN queues to manage the packets by prio and servers
   5  *
   6  * @version 0.01
   7  *
   8  * @date 27-Feb-2008
   9  *
  10  * @author
  11  *      Daniel Sangorrin
  12  *
  13  * @comments
  14  *
  15  * This file contains the FRESCAN queues where frescan packets are stored and
  16  * managed.
  17  *
  18  * @license
  19  *
  20  * See MaRTE OS license
  21  *
  22  */
  23
  24 #ifndef _MARTE_FRESCAN_QUEUES_H_
  25 #define _MARTE_FRESCAN_QUEUES_H_
  26
  27 #include <stdint.h>           // uint8_t
  28 #include <stdbool.h>          // bool
  29
  30 #include "frescan.h"          // frescan_prio_t
  31 #include "frescan_packets.h"  // frescan_packet_t
  32 #include "frescan_data.h"
  33
  34 /**
  35  * frescan_queues_init() - initialize the queues
  36  *
  37  * This function initializes the queue structures for an instance of frescan
  38  * protocol. We provide different sizes and constants so, at initialization
  39  * time, the structures are allocated from the heap. Note, that this approach
  40  * is not conflicting with real-time systems where typically static allocation
  41  * is used because we only do it at the initialization and also because we
  42  * are using a real-time memory allocator. The advantage is that we have the
  43  * flexibility of using different values for different instances of the
  44  * protocol and that we can also supply the protocol compiled as a library.
  45  *
  46  * @queues: the queues structures
  47  * @frescan_init_params_t: some init parameters for the queues
  48  *
  49  * TODO: add maximum number of packets per queue?? so far they are taken from
  50  *       the same pool.
  51  * TODO: add policy for overwritting
  52  */
  53
  54 int frescan_queues_init(frescan_queues_t *queues,
  55                         frescan_init_params_t *params);
  56
  57 /**
  58  * frescan_pqueue_enqueue() - enqueue a packet
  59  *
  60  * this function enqueues a frescan_packet into the a priority queue. For the
  61  * case of same priority packets they are stored at the tail, following a FIFO
  62  * enqueuing policy.
  63  *
  64  * @pqueue: the priority queue
  65  * @packet: the packet that we want to store
  66  *
  67  */
  68
  69 int frescan_pqueue_enqueue(frescan_prio_queue_t *pqueue,
  70                            frescan_packet_t *packet,
  71                            frescan_prio_t prio);
  72
  73 /**
  74  * frescan_pqueue_requeue() - requeue a packet
  75  *
  76  * this function requeues a previously extracted frescan_packet. It puts
  77  * the packet at the head of the fifo queue. This is useful when you abort
  78  * the transmission of the packet beacuse another one with highest priority
  79  * has arrived, and you still want to preserve the order in which the packets
  80  * where enqueued
  81  *
  82  * @pqueue: the priority queue
  83  * @packet: the packet that we want to store
  84  *
  85  */
  86
  87 int frescan_pqueue_requeue(frescan_prio_queue_t *pqueue,
  88                            frescan_packet_t *packet,
  89                            frescan_prio_t prio);
  90
  91 /**
  92  * frescan_pqueue_dequeue() - dequeue the packet with highest priority
  93  *
  94  * @pqueue: the priority queue
  95  * @packet: the packet extracted
  96  * @blocking: if there are no packets we can choose to block or not. In
  97  * a non-blocking mode, if there are no packets 'packet' will be NULL
  98  *
  99  */
 100
 101 int frescan_pqueue_dequeue(frescan_prio_queue_t *pqueue,
 102                            frescan_packet_t **packet,
 103                            frescan_prio_t *packet_prio,
 104                            bool blocking);
 105
 106 /**
 107  * frescan_pqueue_get_highest_prio() - returns the packet with highest prio
 108  * but not extracting it from the queue.
 109  *
 110  * @pqueue: the priority queue
 111  * @packet: the packet with highest prio (not extracted from the pqueue)
 112  *
 113  */
 114
 115 int frescan_pqueue_get_highest_prio(frescan_prio_queue_t *pqueue,
 116                                     frescan_packet_t **packet,
 117                                     frescan_prio_t *packet_prio);
 118
 119 /**
 120  * frescan_servers_enqueue() - enqueue a packet through a server
 121  *
 122  * @net: the network instance
 123  * @id: the identificator for the server
 124  * @packet: the packet being enqueued
 125  *
 126  */
 127
 128 int frescan_servers_enqueue(frescan_network_t net,
 129                             frescan_ss_t id,
 130                             frescan_packet_t *packet);
 131
 132 /**
 133  * frescan_servers_requeue() - requeue a packet through a server
 134  *
 135  * @net: the network instance
 136  * @id: the identificator for the server
 137  * @packet: the packet being requeued
 138  *
 139  */
 140
 141 int frescan_servers_requeue(frescan_network_t net,
 142                             frescan_ss_t id,
 143                             frescan_packet_t *packet);
 144
 145 /**
 146  * frescan_servers_dequeue() - dequeue a packet from a server
 147  *
 148  * @net: the network instance
 149  * @id: the identificator for the server
 150  * @packet: the packet dequeued
 151  *
 152  */
 153
 154 int frescan_servers_dequeue(frescan_network_t net,
 155                             frescan_ss_t id,
 156                             frescan_packet_t **packet,
 157                             frescan_prio_t *packet_prio);
 158
 159 #endif // _MARTE_FRESCAN_QUEUES_H_