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  * -----------------------------------------------------------------------
  21  *  Copyright (C) 2006 - 2008 FRESCOR consortium partners:
  22  *
  23  *    Universidad de Cantabria,              SPAIN
  24  *    University of York,                    UK
  25  *    Scuola Superiore Sant'Anna,            ITALY
  26  *    Kaiserslautern University,             GERMANY
  27  *    Univ. Politécnica  Valencia,           SPAIN
  28  *    Czech Technical University in Prague,  CZECH REPUBLIC
  29  *    ENEA                                   SWEDEN
  30  *    Thales Communication S.A.              FRANCE
  31  *    Visual Tools S.A.                      SPAIN
  32  *    Rapita Systems Ltd                     UK
  33  *    Evidence                               ITALY
  34  *
  35  *    See http://www.frescor.org for a link to partners' websites
  36  *
  37  *           FRESCOR project (FP6/2005/IST/5-034026) is funded
  38  *        in part by the European Union Sixth Framework Programme
  39  *        The European Union is not liable of any use that may be
  40  *        made of this code.
  41  *
  42  *  This file is part of FRESCAN
  43  *
  44  *  FRESCAN is free software; you can  redistribute it and/or  modify
  45  *  it under the terms of  the GNU General Public License as published by
  46  *  the Free Software Foundation;  either  version 2, or (at  your option)
  47  *  any later version.
  48  *
  49  *  FRESCAN  is distributed  in  the hope  that  it  will  be useful,  but
  50  *  WITHOUT  ANY  WARRANTY;     without  even the   implied   warranty  of
  51  *  MERCHANTABILITY  or  FITNESS FOR  A  PARTICULAR PURPOSE. See  the  GNU
  52  *  General Public License for more details.
  53  *
  54  *  You should have  received a  copy of  the  GNU  General Public License
  55  *  distributed  with  FRESCAN;  see file COPYING.   If not,  write to the
  56  *  Free Software  Foundation,  59 Temple Place  -  Suite 330,  Boston, MA
  57  *  02111-1307, USA.
  58  *
  59  * As a special exception, including FRESCAN header files in a file,
  60  * instantiating FRESCAN generics or templates, or linking other files
  61  * with FRESCAN objects to produce an executable application, does not
  62  * by itself cause the resulting executable application to be covered
  63  * by the GNU General Public License. This exception does not
  64  * however invalidate any other reasons why the executable file might be
  65  * covered by the GNU Public License.
  66  * -----------------------------------------------------------------------
  67  *
  68  */
  69
  70 #ifndef _MARTE_FRESCAN_QUEUES_H_
  71 #define _MARTE_FRESCAN_QUEUES_H_
  72
  73 #include <stdint.h>           // uint8_t
  74 #include <stdbool.h>          // bool
  75
  76 #include "frescan.h"          // frescan_prio_t
  77 #include "frescan_packets.h"  // frescan_packet_t
  78 #include "frescan_data.h"
  79
  80 /**
  81  * frescan_queues_init() - initialize the queues
  82  *
  83  * This function initializes the queue structures for an instance of frescan
  84  * protocol. We provide different sizes and constants so, at initialization
  85  * time, the structures are allocated from the heap. Note, that this approach
  86  * is not conflicting with real-time systems where typically static allocation
  87  * is used because we only do it at the initialization and also because we
  88  * are using a real-time memory allocator. The advantage is that we have the
  89  * flexibility of using different values for different instances of the
  90  * protocol and that we can also supply the protocol compiled as a library.
  91  *
  92  * @queues: the queues structures
  93  * @frescan_init_params_t: some init parameters for the queues
  94  *
  95  * TODO: add maximum number of packets per queue?? so far they are taken from
  96  *       the same pool.
  97  * TODO: add policy for overwritting
  98  */
  99
 100 int frescan_queues_init(frescan_queues_t *queues,
 101                         frescan_init_params_t *params);
 102
 103 /**
 104  * frescan_pqueue_enqueue() - enqueue a packet
 105  *
 106  * this function enqueues a frescan_packet into the a priority queue. For the
 107  * case of same priority packets they are stored at the tail, following a FIFO
 108  * enqueuing policy.
 109  *
 110  * @pqueue: the priority queue
 111  * @packet: the packet that we want to store
 112  *
 113  */
 114
 115 int frescan_pqueue_enqueue(frescan_prio_queue_t *pqueue,
 116                            frescan_packet_t *packet,
 117                            frescan_prio_t prio);
 118
 119 /**
 120  * frescan_pqueue_requeue() - requeue a packet
 121  *
 122  * this function requeues a previously extracted frescan_packet. It puts
 123  * the packet at the head of the fifo queue. This is useful when you abort
 124  * the transmission of the packet beacuse another one with highest priority
 125  * has arrived, and you still want to preserve the order in which the packets
 126  * where enqueued
 127  *
 128  * @pqueue: the priority queue
 129  * @packet: the packet that we want to store
 130  *
 131  */
 132
 133 int frescan_pqueue_requeue(frescan_prio_queue_t *pqueue,
 134                            frescan_packet_t *packet,
 135                            frescan_prio_t prio);
 136
 137 /**
 138  * frescan_pqueue_dequeue() - dequeue the packet with highest priority
 139  *
 140  * @pqueue: the priority queue
 141  * @packet: the packet extracted
 142  * @blocking: if there are no packets we can choose to block or not. In
 143  * a non-blocking mode, if there are no packets 'packet' will be NULL
 144  *
 145  */
 146
 147 int frescan_pqueue_dequeue(frescan_prio_queue_t *pqueue,
 148                            frescan_packet_t **packet,
 149                            frescan_prio_t *packet_prio,
 150                            bool blocking);
 151
 152 /**
 153  * frescan_pqueue_get_highest_prio() - returns the packet with highest prio
 154  * but not extracting it from the queue.
 155  *
 156  * @pqueue: the priority queue
 157  * @packet: the packet with highest prio (not extracted from the pqueue)
 158  *
 159  */
 160
 161 int frescan_pqueue_get_highest_prio(frescan_prio_queue_t *pqueue,
 162                                     frescan_packet_t **packet,
 163                                     frescan_prio_t *packet_prio);
 164
 165 /**
 166  * frescan_servers_enqueue() - enqueue a packet through a server
 167  *
 168  * @net: the network instance
 169  * @id: the identificator for the server
 170  * @packet: the packet being enqueued
 171  *
 172  */
 173
 174 int frescan_servers_enqueue(frescan_network_t net,
 175                             frescan_ss_t id,
 176                             frescan_packet_t *packet);
 177
 178 /**
 179  * frescan_servers_requeue() - requeue a packet through a server
 180  *
 181  * @net: the network instance
 182  * @id: the identificator for the server
 183  * @packet: the packet being requeued
 184  *
 185  */
 186
 187 int frescan_servers_requeue(frescan_network_t net,
 188                             frescan_ss_t id,
 189                             frescan_packet_t *packet);
 190
 191 /**
 192  * frescan_servers_dequeue() - dequeue a packet from a server
 193  *
 194  * @net: the network instance
 195  * @id: the identificator for the server
 196  * @packet: the packet dequeued
 197  *
 198  */
 199
 200 int frescan_servers_dequeue(frescan_network_t net,
 201                             frescan_ss_t id,
 202                             frescan_packet_t **packet,
 203                             frescan_prio_t *packet_prio);
 204
 205 #endif // _MARTE_FRESCAN_QUEUES_H_