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