po_hi_gqueue.h 7.82 KB
Newer Older
1
2
3
4
5
/*
 * This is a part of PolyORB-HI-C distribution, a minimal
 * middleware written for generated code from AADL models.
 * You should use it with the Ocarina toolsuite.
 *
yoogx's avatar
yoogx committed
6
 * For more informations, please visit http://taste.tuxfamily.org/wiki
7
 *
8
 * Copyright (C) 2007-2009 Telecom ParisTech, 2010-2017 ESA & ISAE.
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
 */

#ifndef __PO_HI_GQUEUE_H__
#define __PO_HI_GQUEUE_H__

#define __PO_HI_GQUEUE_FULL      10

#define __PO_HI_GQUEUE_FIFO_INDATA    -1
#define __PO_HI_GQUEUE_FIFO_OUT       -2

#define __PO_HI_GQUEUE_INVALID_PORT invalid_port_t
#define __PO_HI_GQUEUE_INVALID_LOCAL_PORT invalid_local_port_t

#include <deployment.h>
#include <request.h>
#include <po_hi_types.h>

Antonia Francis's avatar
Antonia Francis committed
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
/**
 * \brief Initialize a global queue.
 *
 * In a distributed system, each task has
 * its own global queue. This function is invoked by each thead to
 * create its global queue, according to its information (number of
 * ports, destination of each port ...).

 * \param id id of the task associated to this queue.
 * \param nb_ports number of ports for task 'id'.
 * \param queue XXX.
 * \param sizes size of the FIFO for each port, or __PO_HI_GQUEUE_FIFO_OUT if this is an out port.
 * \param first XXX.
 * \param offsets offset position for each queue in the global queue.
 * \param woffsets 
 * \param n_dest number of destinations for each port.
 * \param destinations destination for each port.
 * \param used_size  XXX.
 * \param history  XXX.
 * \param recent  XXX.
 * \param empties  XXX.
 * \param total_fifo_sizes XXX.
 */
49
void __po_hi_gqueue_init (__po_hi_task_id       id,
50
			  __po_hi_port_id_t     nb_ports,
51
			  __po_hi_port_t        queue[],
52
53
54
55
56
			  __po_hi_port_id_t     sizes[],
			  __po_hi_port_id_t     first[],
			  __po_hi_port_id_t     offsets[],
			  __po_hi_port_id_t     woffsets[],
			  __po_hi_port_id_t     n_dest[],
57
			  __po_hi_port_t*       destinations[],
58
			  __po_hi_port_id_t     used_size[],
59
60
			  __po_hi_local_port_t  history[],
			  __po_hi_request_t     recent[],
61
62
			  __po_hi_port_id_t     empties[],
			  __po_hi_uint32_t      total_fifo_size);
63

Antonia Francis's avatar
Antonia Francis committed
64
65
66
67
68
69
70
71
72


/**
 * \brief Store a value for an OUT port.
 * 
 * \param id task-id which owns the global queue.
 * \param port port that store the value (local).
 * \param request pointer towards the request to store in the queue.
 */
73
74
void __po_hi_gqueue_store_out (__po_hi_task_id id,
                               __po_hi_local_port_t port,
75
76
                               __po_hi_request_t* request);

Antonia Francis's avatar
Antonia Francis committed
77
78
79
80
81
82
83
84
85


/*
 * \brief Send a value for an out port.
 * 
 * \param id task-id which has the global queue.
 * \param port number of the port that will send the data.
 * \param request pointer towards the request to store in the queue.
 */
86
/*
87
int __po_hi_gqueue_send_output (__po_hi_task_id id,
88
                                 __po_hi_port_t port);
89
*/
90
91


Antonia Francis's avatar
Antonia Francis committed
92
93
94
95
96
97
/**
 * \brief Get the value on the specified port.
 * 
 * If the port is an output, this function will return nothing,
 * but will not produce an error. 
 * 
98
99
100
 * If the port is an *IN* event port, this function will return 
 * the last value received in the request parameter, or block until an event arrives.
 * 
Antonia Francis's avatar
Antonia Francis committed
101
102
103
104
105
 * \param id task-id which owns the global queue.
 * \param port number of port that received the data.
 * \param request pointer to store the received data.
 * \return 0 if there is no error in the assert.
 */
106
107
int __po_hi_gqueue_get_value(__po_hi_task_id id,
			     __po_hi_local_port_t port,
108
109
			     __po_hi_request_t* request);

Antonia Francis's avatar
Antonia Francis committed
110
111
112
113
/**
 * \brief Dequeue the value on a port.
 * 
 * This function should not be called several times, until
114
 * you know what you do.
Antonia Francis's avatar
Antonia Francis committed
115
116
117
118
 * 
 * \param id task-id in the local process.
 * \param port port number.
 * \return __PO_HI_SUCCESS if there is no error in the assert.
119
 */
Antonia Francis's avatar
Antonia Francis committed
120
121
int __po_hi_gqueue_next_value(__po_hi_task_id id,
			      __po_hi_local_port_t port);
122

Antonia Francis's avatar
Antonia Francis committed
123
124
125
126
127
128
129
/**
 * \brief Return the number of events that are pending of a port.
 * 
 * \param id task-identifier in the local process.
 * \param port port identifier (or port number) for the thread.
 * \return the number of events that are pending of a port.
 */
130
int __po_hi_gqueue_get_count(__po_hi_task_id id,
131
132
			     __po_hi_local_port_t port);

Antonia Francis's avatar
Antonia Francis committed
133
134
135
136
137
138
139
140
/**
 * \brief Wait until an event is received on any port for a given thread.
 * 
 * When the function returns, the port argument will contrain the port-id that received the event.
 * 
 * \param id thread identifier in the local process.
 * \param port pointer to a port value.
 */
141
void __po_hi_gqueue_wait_for_incoming_event(__po_hi_task_id id,
142
143
					    __po_hi_local_port_t* port);

Antonia Francis's avatar
Antonia Francis committed
144
145
146
147
148
149
150
151
152
153
/**
 * \brief Store a value in a IN port.
 * 
 * The request argument contrains the request that will be stored in the queue.
 * 
 * \param id task identifier in the local process.
 * \param port port identifier for the local thread.
 * \param request pointer towards what will be stored in the queue.
 * \return the number of events that are pending of a port.
 */
154
__po_hi_port_id_t __po_hi_gqueue_store_in (__po_hi_task_id id,
155
					 __po_hi_local_port_t port,
156
					 __po_hi_request_t* request);
Antonia Francis's avatar
Antonia Francis committed
157

158
159
160
161
162
163
164
165
166
167
168
169
/**
 * \brief Access the most recent value queued.
 *  
 * The program fetches the most recent value on this port in the __po_hi_gqueue_get_most_recent_value array. 
 * It gives the result in the form of a request.
 * WARNING the function doesn't take into account whether the port is an output or input, if the port is empty or not.
 * For this details, see the function get_value.
 * 
 * \param task_id task identifier in the local process.
 * \param local_port port identifier for the local thread.
 * \return the request.
 */
170
__po_hi_request_t*  __po_hi_gqueue_get_most_recent_value
171
172
173
         (const __po_hi_task_id task_id,
          const __po_hi_local_port_t local_port);

174
175
176
177
178
179
180
181
182
/**
 * \brief Access the destination port thanks to the destination number.
 *  
 * The program fetches the destination port.
 * \param task_id task identifier in the local process.
 * \param local_port port identifier for the local thread.
 * \param destination_number the number of the destination (__po_hi_gqueue_get_destinations_number function).
 * \return the port.
 */
183
184
185
__po_hi_port_t __po_hi_gqueue_get_destination (const __po_hi_task_id task_id,
                                               const __po_hi_local_port_t local_port,
                                               const uint8_t destination_number);
186

187
188
189
190
191
192
193
194
195
196
197
198
/**
 * \brief Access the destination number (for a specified port).
 *  
 * The program fetches the destination number in the __po_hi_gqueues_n_destinations array.
 * It gives the destination number in the form of a __po_hi_port_id_t.
 * It can be used then to get the destination port with the get_destination function.
 * 
 * \param task_id task identifier in the local process.
 * \param local_port port identifier for the local thread.
 * \return the number.
 */
__po_hi_port_id_t __po_hi_gqueue_get_destinations_number (const __po_hi_task_id task_id,
199
                                                const __po_hi_local_port_t local_port);
200

201

Antonia Francis's avatar
Antonia Francis committed
202
203
204
205
206
207
208
/**
 * \brief Access the size of a port. 
 * 
 * \param id task identifier in the local process.
 * \param port port identifier for the local thread.
 * \return size of port.
 */
209
__po_hi_port_id_t __po_hi_gqueue_get_port_size(const __po_hi_task_id id,
210
211
                                            const __po_hi_local_port_t port);

Antonia Francis's avatar
Antonia Francis committed
212
213
214
215
216
217
/**
 * \brief Access the used size of a port. 
 * 
 * \param id task identifier in the local process.
 * \param port port identifier for the local thread.
 * \return size of port.
218
 */
219
__po_hi_port_id_t __po_hi_gqueue_used_size( __po_hi_task_id id, __po_hi_local_port_t port);
220

221
222
223
224
225
226
227
228
/**
 * \brief Check whether the queue belonging to the id task is empty.
 *  
 * The program checks the array __po_hi_gqueues_queue_is_empty.
 * \param id task identifier in the local process.
 * \return the value in the array.
 * \return 0 and 1 if the queue is not empty because of array construction.
 */
229
__po_hi_port_id_t  po_hi_gqueues_queue_is_empty(__po_hi_task_id id);
230

231
#endif /* __PO_HI_GQUEUE_H__ */