po_hi_gqueue.h 9.92 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_request_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);

133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
/**
 * \brief Compute dispatch condition :
 * return 1 when the condition of one of the transitions that stemmed from the next 
 * complete state is verified (i.e. all its dispatch triggers received events on 
 * their corresponding ports) else return 0. 
 * It also sets the index of the transition to execute according to the condition that is
 * verified.
 *
 * \param id thread identifier in the local process.
 * \param next_complete_state the struct that contains arrays informations about 
 * transitions and dispatch triggers of the next complete state.
 * \param initial_sizes_of_dispatch_triggers_of_all_transitions array that contains the number of
 * events that are pending each dispatch ports of all transitions.
 * \param index_transition_to_execute the index of transition to execute,
 * this parameter will be set according to the transition whose condition is verified.
 */
__po_hi_bool_t __po_hi_gqueue_compute_index_transition_to_execute  (__po_hi_task_id id,
                                                                    __po_hi_ba_automata_state_t* next_complete_state,
                                                                    int* initial_sizes_of_dispatch_triggers_of_all_transitions,
                                                                    __po_hi_int32_t* index_transition_to_execute);

/**
 * \brief Wait until all the specified dispatch events (according to the next complete state) 
 * are received on the corresponding ports for a given thread.
 *
 * \param id thread identifier in the local process.
 * \param next_complete_state the struct that contains arrays informations about 
 * transitions and dispatch triggers of the next complete state.
 * \param index_transition_to_execute the index of transition to execute,
 * this parameter will be set according to the transition whose condition is verified.
 */
 void __po_hi_gqueue_wait_for_specific_incoming_events (__po_hi_task_id id,
                                                       __po_hi_ba_automata_state_t* next_complete_state,
                                                       __po_hi_int32_t* index_transition_to_execute);


Antonia Francis's avatar
Antonia Francis committed
169
170
171
172
173
174
175
176
/**
 * \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.
 */
177
void __po_hi_gqueue_wait_for_incoming_event(__po_hi_task_id id,
178
179
					    __po_hi_local_port_t* port);

Antonia Francis's avatar
Antonia Francis committed
180
181
182
183
184
185
186
187
188
189
/**
 * \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.
 */
190
__po_hi_port_id_t __po_hi_gqueue_store_in (__po_hi_task_id id,
191
					 __po_hi_local_port_t port,
192
					 __po_hi_request_t* request);
Antonia Francis's avatar
Antonia Francis committed
193

194
195
196
197
198
199
200
201
202
203
204
205
/**
 * \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.
 */
206
__po_hi_request_t*  __po_hi_gqueue_get_most_recent_value
207
208
209
         (const __po_hi_task_id task_id,
          const __po_hi_local_port_t local_port);

210
211
212
213
214
215
216
217
218
/**
 * \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.
 */
219
220
221
__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);
222

223
224
225
226
227
228
229
230
231
232
233
234
/**
 * \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,
235
                                                const __po_hi_local_port_t local_port);
236

237

Antonia Francis's avatar
Antonia Francis committed
238
239
240
241
242
243
244
/**
 * \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.
 */
245
__po_hi_port_id_t __po_hi_gqueue_get_port_size(const __po_hi_task_id id,
246
247
                                            const __po_hi_local_port_t port);

Antonia Francis's avatar
Antonia Francis committed
248
249
250
251
252
253
/**
 * \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.
254
 */
255
__po_hi_port_id_t __po_hi_gqueue_used_size( __po_hi_task_id id, __po_hi_local_port_t port);
256

257
258
259
260
261
262
263
264
/**
 * \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.
 */
265
__po_hi_port_id_t  po_hi_gqueues_queue_is_empty(__po_hi_task_id id);
266

267
#endif /* __PO_HI_GQUEUE_H__ */