Rev 929 | Go to most recent revision | Details | Last modification | View Log | RSS feed
Rev | Author | Line No. | Line |
---|---|---|---|
899 | trimarchi | 1 | //fsf_distributed.h |
2 | //===================================================================== |
||
3 | // FFFFFFIII RRRRR SSTTTTTTT |
||
4 | // FF IIR RR SS |
||
5 | // FF IR SS |
||
6 | // FFFFFF RRRR SSSSST |
||
7 | // FF FI RRR SS |
||
8 | // FF II RRR SS |
||
9 | // FF IIIIIR RS |
||
10 | // |
||
11 | // FSF(FIRST Scheduling Framework) |
||
12 | // distributed services functionality |
||
13 | //===================================================================== |
||
14 | |||
15 | #include "fsf_core.h" |
||
16 | |||
17 | #ifndef _FSF_DISTRIBUTED_H_ |
||
18 | #define _FSF_DISTRIBUTED_H_ |
||
19 | |||
20 | #define FSF_DISTRIBUTED_MODULE_SUPPORTED 1 |
||
21 | |||
22 | |||
23 | //This operation identifies a contract as a |
||
24 | //bandwidth reservation on the network identified |
||
25 | //by the network input parameter. Then the |
||
26 | //contract negotiation is performed using the |
||
27 | //conventional negotiation functions, including |
||
28 | //the possibility of grouping the contract with |
||
29 | //others. If the network_id given is |
||
30 | //FSF_NULL_NETWORK_ID, the contract is considered |
||
31 | //not to reserve bandwidth in a network but to |
||
32 | //operate as any other regular contract. It |
||
33 | //returns 0 if successful, or FSF_ERR_BAD_ARGUMENT |
||
34 | //if contract is null or the network id is not |
||
35 | //valid. |
||
36 | |||
37 | int |
||
38 | fsf_set_contract_network_id |
||
39 | (fsf_contract_parameters_t *contract, |
||
40 | fsf_network_id_t network_id); |
||
41 | |||
42 | |||
43 | //This operation puts the network identification |
||
44 | //corresponding to the contract parameters object |
||
45 | //pointed to by contract in the variable pointed |
||
46 | //to by network_id. If the contract is a regular |
||
47 | //one and therefore has not a network_id set, it |
||
48 | //puts the FSF_NULL_NETWORK_ID constant instead. |
||
49 | //it returns 0 if successful, or |
||
50 | //FSF_ERR_BAD_ARGUMENT if any of the pointers is |
||
51 | //null. |
||
52 | |||
53 | int |
||
54 | fsf_get_contract_network_id |
||
55 | (const fsf_contract_parameters_t *contract, |
||
56 | fsf_network_id_t *network_id); |
||
57 | |||
58 | //Transmission services: |
||
59 | |||
60 | //opaque types for fsf endpoints |
||
61 | typedef FSF_SEND_ENDPOINT_T_OPAQUE fsf_send_endpoint_t; |
||
62 | typedef FSF_RECEIVE_ENDPOINT_T_OPAQUE fsf_receive_endpoint_t; |
||
63 | |||
64 | //The node_address type specifies the node address |
||
65 | //in a communication-protocol-independent way. The actual |
||
66 | //address is obtained via a configuration dependent mapping |
||
67 | //function |
||
68 | typedef unsigned int fsf_node_address_t; |
||
69 | |||
70 | //The port type specifies the information that is |
||
71 | //necessary to get in contact with the thread in the |
||
72 | //receiving node, in a protocol-independent way. |
||
73 | //The actual port number is obtained via a configuration |
||
74 | //dependent mapping function |
||
75 | typedef unsigned int fsf_port_t; |
||
76 | |||
77 | //This operation creates a unidirectional input |
||
78 | //data endpoint through which, after the |
||
79 | //corresponding binding, it is possible to send |
||
80 | //data. network_id identifies the network to use, |
||
81 | //receiver specifies the communication protocol |
||
82 | //dependent information that is necessary to |
||
83 | //address the receiving node, and port specifies |
||
84 | //the communication protocol dependent information |
||
85 | //that is necessary to get in contact with the |
||
86 | //desired destination. |
||
87 | //It returns 0 if |
||
88 | //successful. It returns FSF_ERR_BAD_ARGUMENT if |
||
89 | //the endpoint is null, if the network_id is not |
||
90 | //valid, or if the receiver or the port do not |
||
91 | //conform to their expected formats. |
||
92 | int |
||
93 | fsf_create_send_endpoint |
||
94 | (fsf_network_id_t network_id, |
||
95 | fsf_node_address_t receiver, |
||
96 | fsf_port_t port, |
||
97 | fsf_send_endpoint_t *endpoint); |
||
98 | |||
99 | //This operation eliminates any resources reserved |
||
100 | //for the referenced endpoint. If the endpoint is |
||
101 | //bound to a network server, it is unbound from it |
||
102 | //and can not be further used to invoke send |
||
103 | //operations on it. |
||
104 | //It returns 0 if successful, |
||
105 | //or FSF_ERR_BAD_ARGUMENT if the endpoint is not |
||
106 | //valid. |
||
107 | int |
||
108 | fsf_destroy_send_endpoint |
||
109 | (fsf_send_endpoint_t *endpoint); |
||
110 | |||
111 | //This operation returns (except for those NULL |
||
112 | //arguments) in the variables pointed to by |
||
113 | //network_id, receiver, or port, the corresponding |
||
114 | //parameters used in the creation of the given |
||
115 | //send endpoint. It returns 0 if successful, or |
||
116 | //FSF_ERR_BAD_ARGUMENT if the endpoint is not |
||
117 | //valid. |
||
118 | int |
||
119 | fsf_get_send_endpoint_parameters |
||
120 | (const fsf_send_endpoint_t *endpoint, |
||
121 | fsf_network_id_t *network_id, |
||
122 | fsf_node_address_t *receiver, |
||
123 | fsf_port_t *port); |
||
124 | |||
125 | //This operation associates a send endpoint with a |
||
126 | //server, which means that messages sent through |
||
127 | //that endpoint will consume the server's reserved |
||
128 | //bandwidth and its packets will be sent according |
||
129 | //to the contract established for that server. If |
||
130 | //the endpoint is already bound to another server, |
||
131 | //it is effectively unbound from it and bound to |
||
132 | //the specified one. |
||
133 | //The operation returns 0 if successful, or |
||
134 | //FSF_ERR_BAD_ARGUMENT if the endpoint or the server |
||
135 | //are not valid, it also fails with a |
||
136 | //value of FSF_ERR_ALREADY_BOUND if the server is |
||
137 | //already bound to some other send endpoint. |
||
138 | //It fails with FSF_ERR_WRONG_NETWORK if the server |
||
139 | //network id is not the same as the one in the endpoint |
||
140 | int |
||
141 | fsf_bind_endpoint_to_server |
||
142 | (fsf_server_id_t server, |
||
143 | fsf_send_endpoint_t *endpoint); |
||
144 | |||
145 | //This operation unbinds a send endpoint from a |
||
146 | //server Endpoints with no server associated |
||
147 | //cannot be used to send data, and they stay in |
||
148 | //that state until they are either eliminated or |
||
149 | //bound again. The operation fails with |
||
150 | //FSF_ERR_NOT_BOUND if the endpoint has no server |
||
151 | //bound |
||
152 | int |
||
153 | fsf_unbind_endpoint_from_server |
||
154 | (fsf_send_endpoint_t *endpoint); |
||
155 | |||
156 | //This operation copies the id of the server that |
||
157 | //is bound to the specified send endpoint into the |
||
158 | //variable pointed to by server. It returns 0 if |
||
159 | //successful, or FSF_ERR_BAD_ARGUMENT if the |
||
160 | //endpoint is not valid or server is NULL |
||
161 | int |
||
162 | fsf_get_endpoint_server |
||
163 | (const fsf_send_endpoint_t *endpoint, |
||
164 | fsf_server_id_t *server); |
||
165 | |||
166 | //This operation sends a message stored in msg and of length size |
||
167 | //through the given endpoint. The operation is non-blocking and |
||
168 | //returns immediately. An internal fsf service will schedule the |
||
169 | //sending of messages and implement the communications sporadic server |
||
170 | //corresponding to the network server bound to the given endpoint. |
||
171 | //Messages sent through the same endpoint are received in the same |
||
172 | //order in which they were sent It returns 0 if successful, but it |
||
173 | //fails with FSF_ERR_BAD_ARGUMENT if endpoint is not valid; it fails |
||
174 | //with FSF_ERR_NOT_BOUND is not bound to a valid server; it fails with |
||
175 | //FSF_ERR_TOO_LARGE if the message is too large for the network |
||
176 | //protocol; it fails with FSF_ERR_BUFFER_FULL if the sending queue is |
||
177 | //full |
||
178 | int |
||
179 | fsf_send |
||
180 | (const fsf_send_endpoint_t *endpoint, |
||
181 | void *msg, |
||
182 | size_t size); |
||
183 | |||
184 | //This operation creates a receive endpoint with all the information |
||
185 | //that is necessary to receive information from the specified network |
||
186 | //and port It returns 0 if successful, but it fails with |
||
187 | //FSF_ERR_BAD_ARGUMENT if the port or the network id are not valid. |
||
188 | int |
||
189 | fsf_create_receive_endpoint |
||
190 | (fsf_network_id_t network_id, |
||
191 | fsf_port_t port, |
||
192 | fsf_receive_endpoint_t *endpoint); |
||
193 | |||
194 | //If there are no messages available in the specified receive endpoint |
||
195 | //this operation blocks the calling thread waiting for a message to be |
||
196 | //received. When a message is available, if its size is less than or |
||
197 | //equal to the buffersize, the function stores it in the variable |
||
198 | //pointed to by buffer and puts the number of bytes received in the |
||
199 | //variable pointed to by messagesize. The function fails with |
||
200 | //FSF_ERR_NO_SPACE if the buffersize is too small for the message |
||
201 | //received (in which case the message is lost), or with |
||
202 | //FSF_ERR_BAD_ARGUMENT if the endpoint is not valid, or if buffer or |
||
203 | //messagesize are NULL. Messages arriving at a receiver buffer that |
||
204 | //is full will be silently discarded. The application is responsible |
||
205 | //of reading the receive endpoints with appropriate regularity, or of |
||
206 | //using a sequence number or some other mechanism to detect any lost |
||
207 | //messages. |
||
208 | int |
||
209 | fsf_receive |
||
210 | (const fsf_receive_endpoint_t *endpoint, |
||
211 | void *buffer, |
||
212 | size_t buffersize, |
||
213 | size_t *messagesize); |
||
214 | |||
215 | //This operation is the same as fsf_receive, except |
||
216 | //that if there are no messages available in the |
||
217 | //specified receive endpoint at the time of the call |
||
218 | //the operation returns with an error of |
||
219 | //FSF_ERR_NO_MESSAGES |
||
220 | int |
||
221 | fsf_try_receive |
||
222 | (const fsf_receive_endpoint_t *endpoint, |
||
223 | void *buffer, |
||
224 | size_t buffersize, |
||
225 | size_t *messagesize); |
||
226 | |||
227 | //This operation is used to calculate the minimum and/or maximum |
||
228 | //budgets used in the preparation of network contracts. It puts in the |
||
229 | //variable pointed to by budget the transmission time that it takes to |
||
230 | //send a message of size msg_size through the network designated by |
||
231 | //network_id, when there is no contention, but including any network |
||
232 | //overheads It returns FSF_ERR_BAD_ARGUMENT if network_id is not a |
||
233 | //valid identifier or if budget is a NULL pointer. |
||
234 | int |
||
235 | fsf_tx_time |
||
236 | (fsf_network_id_t network_id, |
||
237 | size_t msg_size, |
||
238 | struct timespec *budget); |
||
239 | |||
240 | //This operation is used to obtain the maximum message size for the |
||
241 | //specified network It returns FSF_ERR_BAD_ARGUMENT if network_id is |
||
242 | //not a valid identifier or if max_msg_size is NULL |
||
243 | int |
||
244 | fsf_max_message_size |
||
245 | (fsf_network_id_t network_id, |
||
246 | size_t *max_msg_size); |
||
247 | |||
248 | |||
249 | #endif // _FSF_DISTRIBUTED_H_ |