Subversion Repositories shark

Rev

Rev 899 | Rev 985 | Go to most recent revision | Details | Compare with Previous | Last modification | View Log | RSS feed

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