2 * @file frescan_queues.h
4 * @brief FRESCAN queues to manage the packets by prio and servers
15 * This file contains the FRESCAN queues where frescan packets are stored and
20 * -----------------------------------------------------------------------
21 * Copyright (C) 2006 - 2008 FRESCOR consortium partners:
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
30 * Thales Communication S.A. FRANCE
31 * Visual Tools S.A. SPAIN
32 * Rapita Systems Ltd UK
35 * See http://www.frescor.org for a link to partners' websites
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
42 * This file is part of FRESCAN
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)
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.
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
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 * -----------------------------------------------------------------------
70 #ifndef _MARTE_FRESCAN_QUEUES_H_
71 #define _MARTE_FRESCAN_QUEUES_H_
73 #include "frescan_types.h"
76 * frescan_queues_init() - initialize the queues
78 * This function initializes the queue structures for an instance of frescan
79 * protocol. We provide different sizes and constants so, at initialization
80 * time, the structures are allocated from the heap. Note, that this approach
81 * is not conflicting with real-time systems where typically static allocation
82 * is used because we only do it at the initialization and also because we
83 * are using a real-time memory allocator. The advantage is that we have the
84 * flexibility of using different values for different instances of the
85 * protocol and that we can also supply the protocol compiled as a library.
87 * @queues: the queues structures
88 * @frescan_init_params_t: some init parameters for the queues
90 * TODO: add maximum number of packets per queue?? so far they are taken from
92 * TODO: add policy for overwritting
95 int frescan_queues_init(frescan_queues_t *queues,
96 frescan_init_params_t *params);
99 * frescan_pqueue_enqueue() - enqueue a packet
101 * this function enqueues a frescan_packet into the a priority queue. For the
102 * case of same priority packets they are stored at the tail, following a FIFO
105 * @pqueue: the priority queue
106 * @packet: the packet that we want to store
110 int frescan_pqueue_enqueue(frescan_prio_queue_t *pqueue,
111 frescan_packet_t *packet,
112 frescan_prio_t prio);
115 * frescan_pqueue_requeue() - requeue a packet
117 * this function requeues a previously extracted frescan_packet. It puts
118 * the packet at the head of the fifo queue. This is useful when you abort
119 * the transmission of the packet beacuse another one with highest priority
120 * has arrived, and you still want to preserve the order in which the packets
123 * @pqueue: the priority queue
124 * @packet: the packet that we want to store
128 int frescan_pqueue_requeue(frescan_prio_queue_t *pqueue,
129 frescan_packet_t *packet,
130 frescan_prio_t prio);
133 * frescan_pqueue_dequeue() - dequeue the packet with highest priority
135 * @pqueue: the priority queue
136 * @packet: the packet extracted
137 * @blocking: if there are no packets we can choose to block or not. In
138 * a non-blocking mode, if there are no packets 'packet' will be NULL
142 int frescan_pqueue_dequeue(frescan_prio_queue_t *pqueue,
143 frescan_packet_t **packet,
144 frescan_prio_t *packet_prio,
148 * frescan_pqueue_get_highest_prio() - returns the packet with highest prio
149 * but not extracting it from the queue.
151 * @pqueue: the priority queue
152 * @packet: the packet with highest prio (not extracted from the pqueue)
156 int frescan_pqueue_get_highest_prio(frescan_prio_queue_t *pqueue,
157 frescan_packet_t **packet,
158 frescan_prio_t *packet_prio);
161 * frescan_servers_enqueue() - enqueue a packet through a server
163 * @net: the network instance
164 * @id: the identificator for the server
165 * @packet: the packet being enqueued
169 int frescan_servers_enqueue(frescan_network_t net,
171 frescan_packet_t *packet);
174 * frescan_servers_requeue() - requeue a packet through a server
176 * @net: the network instance
177 * @id: the identificator for the server
178 * @packet: the packet being requeued
182 int frescan_servers_requeue(frescan_network_t net,
184 frescan_packet_t *packet);
187 * frescan_servers_dequeue() - dequeue a packet from a server
189 * @net: the network instance
190 * @id: the identificator for the server
191 * @packet: the packet dequeued
195 int frescan_servers_dequeue(frescan_network_t net,
197 frescan_packet_t **packet,
198 frescan_prio_t *packet_prio);
200 #endif // _MARTE_FRESCAN_QUEUES_H_