Subversion Repositories shark

Rev

Rev 986 | 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
 
993 lipari 31
   This operation sets the network id attribute in the contract
32
   pointed to by parameter contract, to the value specified by
33
   network_id.  When a contract is negotiated, if network_id is
34
   FSF_NULL_NETWORK_ID (which is the default value) the contract is
35
   negotiated for the processing capacity of the node making the
36
   call. If network_id represents a valid network identifier, the
37
   negotiation is carried out for the specified network.
38
 
985 julio 39
   @param contract          the pointer to the contract object
40
   @param [in] network_id   the network identifier
41
 
42
   @retval 0 if the operation is succesful
43
   @retval FSF_ERR_BAD_ARGUMENT if contract is null or the network
44
     id is not valid.
929 lipari 45
*/
899 trimarchi 46
int
47
fsf_set_contract_network_id
48
  (fsf_contract_parameters_t *contract,
49
   fsf_network_id_t           network_id);
50
 
929 lipari 51
/**
899 trimarchi 52
 
929 lipari 53
   \ingroup distjmodule
985 julio 54
 
55
   This operation puts the network identification
56
   corresponding to the contract parameters object
57
   pointed to by contract in the variable pointed
58
   to by network_id. If the contract is not a network
59
   one and therefore has not a network_id set, it
60
   puts the FSF_NULL_NETWORK_ID constant instead.
899 trimarchi 61
 
985 julio 62
   @param [in] contract     the pointer to the contract object
63
   @param [out] network_id  pointer to the variable that will contain
64
     the network identifier
65
 
66
   @retval 0 if the operation is succesful
67
   @retval FSF_ERR_BAD_ARGUMENT if any of the pointers is null.
929 lipari 68
*/
899 trimarchi 69
int
70
fsf_get_contract_network_id
71
  (const fsf_contract_parameters_t *contract,
72
   fsf_network_id_t                *network_id);
73
 
985 julio 74
 
899 trimarchi 75
//Transmission services:
76
 
929 lipari 77
/**
78
 
79
   \ingroup distjmodule
80
 
985 julio 81
   This operation creates a unidirectional input
82
   data endpoint through which, after the
83
   corresponding binding, it is possible to send
84
   data.  network_id identifies the network to use,
85
   receiver specifies the communication protocol
86
   dependent information that is necessary to
87
   address the receiving node, and port specifies
88
   the communication protocol dependent information
89
   that is necessary to get in contact with the
90
   desired destination.  
899 trimarchi 91
 
985 julio 92
   @param [in] network_id the identifier ot the network to use
93
   @param [in] receiver   protocol dependent information used
94
     to address the receiving node
95
   @param [in] port       protocol dependent information used
96
     to get in contact with the desired destination process
97
   @param [out] endpoint  pointer to the variable that will
98
     contain the send endpoint
99
 
100
   @retval 0 if the operation is succesful
101
   @retval FSF_ERR_BAD_ARGUMENT if endpoint is null, netwok_id
102
     is not valid or if the receiver or the port do not conform
103
     to their expected formats
929 lipari 104
*/
899 trimarchi 105
int
106
fsf_create_send_endpoint
107
  (fsf_network_id_t      network_id,
108
   fsf_node_address_t    receiver,
109
   fsf_port_t            port,
110
   fsf_send_endpoint_t  *endpoint);
111
 
929 lipari 112
/**
113
   \ingroup distjmodule
114
 
985 julio 115
   This operation eliminates any resources reserved
116
   for the referenced endpoint. If the endpoint is
117
   bound to a network server, it is unbound from it
118
   and can not be further used to invoke send
119
   operations on it.  
120
 
121
   @param endpoint        pointer to the endpoint to eliminate
122
 
123
   @retval 0 if the operation is succesful
124
   @retval FSF_ERR_BAD_ARGUMENT if endpoint is null, or not valid
929 lipari 125
*/
899 trimarchi 126
int
127
fsf_destroy_send_endpoint
128
  (fsf_send_endpoint_t  *endpoint);
129
 
929 lipari 130
/**
131
   \ingroup distjmodule
132
 
985 julio 133
   This operation returns (except for those NULL
134
   arguments) in the variables pointed to by
135
   network_id, receiver, or port, the corresponding
136
   parameters used in the creation of the given
137
   send endpoint.
138
 
139
   @param [in] endpoint     pointer to the endpoint
140
   @param [out] network_id  pointer to variable the will contain
141
     the network id
142
   @param [out] receiver    pointer to variable the will contain
143
     the protocol dependent information used to address the
144
     receiving node
145
   @param [out] port        pointer to variable the will contain
146
     the protocol dependent information used to get in contact
147
     with the desired destination process
148
 
149
   @retval 0 if the operation is succesful
150
   @retval FSF_ERR_BAD_ARGUMENT if endpoint is null, or not valid
151
     or all the other pointers are NULL.
152
 
929 lipari 153
*/
899 trimarchi 154
int
155
fsf_get_send_endpoint_parameters
156
  (const fsf_send_endpoint_t  *endpoint,
157
   fsf_network_id_t           *network_id,
158
   fsf_node_address_t         *receiver,
159
   fsf_port_t                 *port);
160
 
929 lipari 161
/**
162
   \ingroup distjmodule
163
 
985 julio 164
   This operation associates a send endpoint with a
165
   server, which means that messages sent through
166
   that endpoint will consume the server's reserved
167
   bandwidth and its packets will be sent according
168
   to the contract established for that server.  If
169
   the endpoint is already bound to another server,
170
   it is effectively unbound from it and bound to
171
   the specified one.  
172
 
173
   @param [in] server       server id
174
   @param endpoint          pointer to the endpoint
175
 
176
   @retval 0 if the operation is succesful
177
   @retval FSF_ERR_BAD_ARGUMENT if endpoint is null, or not valid
178
     or server is not valid.
179
   @retval FSF_ERR_ALREADY_BOUND if the server is already
180
     bound to some other send endpoint
181
   @retval FSF_ERR_WRONG_NETWORK if the server network id
182
     is not the same as the one in the endpoint
183
*/
899 trimarchi 184
int
929 lipari 185
fsf_bind_endpoint_to_server
186
  (fsf_server_id_t server,
187
   fsf_send_endpoint_t *endpoint);
899 trimarchi 188
 
929 lipari 189
/**
190
   \ingroup distjmodule
191
 
985 julio 192
   This operation unbinds a send endpoint from a
193
   server. Endpoints with no server associated
194
   cannot be used to send data, and they stay in
195
   that state  until they are either eliminated or
196
   bound again.  
197
 
198
   @param endpoint        pointer to the endpoint to unbind
199
 
200
   @retval 0 if the operation is succesful
201
   @retval FSF_ERR_BAD_ARGUMENT if endpoint is null, or not valid
202
   @retval FSF_ERR_NOT_BOUND if the endpoint has no server
203
     bound
204
 */
899 trimarchi 205
int
206
fsf_unbind_endpoint_from_server
207
  (fsf_send_endpoint_t  *endpoint);
208
 
929 lipari 209
/**
210
   \ingroup distjmodule
211
 
985 julio 212
   This operation copies the id of the server that
213
   is bound to the specified send endpoint into the
214
   variable pointed to by server.
215
 
216
   @param [in] endpoint      pointer to the endpoint
217
   @param [out] server       pointer to variable the will contain
218
     the server id
219
 
220
   @retval 0 if the operation is succesful
221
   @retval FSF_ERR_BAD_ARGUMENT if endpoint is null, or not valid
222
     or server is NULL.
929 lipari 223
*/
899 trimarchi 224
int
225
fsf_get_endpoint_server
226
  (const fsf_send_endpoint_t  *endpoint,
227
   fsf_server_id_t            *server);
228
 
929 lipari 229
 
230
/**
231
   \ingroup distjmodule
232
 
985 julio 233
   This operation sends a message stored in msg and of length size
234
   through the given endpoint. The operation is non-blocking and
235
   returns immediately. An internal fsf service will schedule the
236
   sending of messages and implement the communications sporadic server
237
   corresponding to the network server bound to the given endpoint.
238
   Messages sent through the same endpoint are received in the same
239
   order in which they were sent
240
 
241
   @param endpoint      pointer to the endpoint
242
   @param [in] msg      pointer to the message
243
   @param [in] size     number of bytes to transmitt
244
 
245
   @retval 0 if the operation is succesful
246
   @retval FSF_ERR_BAD_ARGUMENT if endpoint is null, or not valid
247
     or msg is NULL
248
   @retval FSF_ERR_NOT_BOUND if endpoint is not bound to a valid
249
     server;
250
   @retval FSF_ERR_TOO_LARGE if the message is too large for the
251
     network protocol
252
   @retval FSF_ERR_BUFFER_FULL if the sending queue is full
253
*/
899 trimarchi 254
int
255
fsf_send
256
  (const fsf_send_endpoint_t  *endpoint,
257
   void                       *msg,
258
   size_t                      size);
259
 
929 lipari 260
/**
261
   \ingroup distjmodule
262
 
985 julio 263
   This operation creates a receive endpoint with all the information
264
   that is necessary to receive information from the specified network
265
   and port
266
 
267
   @param [in] network_id the identifier ot the network to use
268
   @param [in] port       protocol dependent information used
269
     to identify the calling process as an expecting destination
270
   @param [out] endpoint  pointer to the variable that will
271
     contain the receive endpoint
272
 
273
   @retval 0 if the operation is succesful
274
   @retval FSF_ERR_BAD_ARGUMENT if endpoint is null, network_id
275
     is not valid or if port do not conform to the expected format
276
*/
899 trimarchi 277
int
278
fsf_create_receive_endpoint
279
  (fsf_network_id_t         network_id,
280
   fsf_port_t               port,
281
   fsf_receive_endpoint_t  *endpoint);
282
 
929 lipari 283
/**
284
   \ingroup distjmodule
285
 
986 julio 286
   This operation eliminates any resources reserved for the given
287
   endpoint. After callling this operation the endpoint can not be
288
   further used to invoke receive operations on it.
289
 
290
   @param endpoint         pointer to the endpoint
291
 
292
   @retval 0 if the operation is succesful
293
   @retval FSF_ERR_BAD_ARGUMENT if endpoint is null, or not valid
294
*/
295
int
296
fsf_destroy_receive_endpoint
297
  (fsf_receive_endpoint_t  *endpoint);
298
 
299
 
300
/**
301
   \ingroup distjmodule
302
 
303
   This operation returns in the variables network_id,
304
   and port, the corresponding parameters used in the
305
   creation of the given receive endpoint.
306
 
307
   @param [in] endpoint     pointer to the endpoint
308
   @param [out] network_id  pointer to variable the will contain
309
     the network id
310
   @param [out] port        pointer to variable the will contain
311
     the protocol dependent information used to get in contact
312
     with the desired destination process
313
 
314
   @retval 0 if the operation is succesful
315
   @retval FSF_ERR_BAD_ARGUMENT if endpoint is null, or not valid
316
     or all the other pointers are NULL.
317
*/
318
int
319
fsf_get_receive_endpoint_parameters
320
  (fsf_receive_endpoint_t  *endpoint,
321
   fsf_network_id_t        *network_id,
322
   fsf_port_t              *port);
323
 
324
 
325
/**
326
   \ingroup distjmodule
327
 
985 julio 328
   If there are no messages available in the specified receive endpoint
329
   this operation blocks the calling thread waiting for a message to be
330
   received. When a message is available, if its size is less than or
331
   equal to the buffersize, the function stores it in the variable
332
   pointed to by buffer and puts the number of bytes received in the
333
   variable pointed to by messagesize. Messages arriving at a receiver
334
   buffer that is full will be silently discarded. The application is
335
   responsible of reading the receive endpoints with appropriate
336
   regularity, or of using a sequence number or some other mechanism
337
   to detect any lost messages.
338
 
339
   @param endpoint          pointer to the endpoint
340
   @param [out] buffer      pointer to the place that will contain
341
     the message received
342
   @param [in] buffersize   size of the buffer space
343
   @param [out] messagesize pointer to the variable that will contain
344
     the number of bytes received
345
 
346
   @retval 0 if the operation is succesful
347
   @retval FSF_ERR_BAD_ARGUMENT if endpoint is null, or not valid
348
     or if buffer or messagesize are NULL.
349
   @retval FSF_ERR_NO_SPACE if the buffersize is too small for the
350
     message received (in which case the message is lost).  
351
*/
899 trimarchi 352
int
353
fsf_receive
354
  (const fsf_receive_endpoint_t  *endpoint,
355
   void                          *buffer,
356
   size_t                         buffersize,
357
   size_t                        *messagesize);
358
 
929 lipari 359
/**
360
   \ingroup distjmodule
361
 
985 julio 362
   This operation is the same as fsf_receive, except
363
   that if there are no messages available in the
364
   specified receive endpoint at the time of the call
365
   the operation returns with an error
366
 
367
   @param endpoint          pointer to the endpoint
368
   @param [out] buffer      pointer to the place that will contain
369
     the message received
370
   @param [in] buffersize   size of the buffer space
371
   @param [out] messagesize pointer to the variable that will contain
372
     the number of bytes received
373
 
374
   @retval 0 if the operation is succesful
375
   @retval FSF_ERR_BAD_ARGUMENT if endpoint is null, or not valid
376
     or if buffer or messagesize are NULL.
377
   @retval FSF_ERR_NO_SPACE if the buffersize is too small for the
378
     message received (in which case the message is lost).  
379
   @retval FSF_ERR_NO_MESSAGES if there are no messages available
380
     in the specified receive endpoint at the time of the call
381
*/
899 trimarchi 382
int
383
fsf_try_receive
384
  (const fsf_receive_endpoint_t  *endpoint,
385
   void                          *buffer,
386
   size_t                         buffersize,
387
   size_t                        *messagesize);
388
 
929 lipari 389
/**
390
   \ingroup distjmodule
391
 
985 julio 392
   This operation is used to calculate a budget represented as
393
   a time magnitude, for a specified network. If succesful, the
394
   operation puts in the variable pointed to by budget the
395
   transmission time that it takes to send a packet through the
396
   network designated by network_id, when there is no contention,
397
   but including any network overheads.
993 lipari 398
 
985 julio 399
   @param [in] network_id  the identifier ot the network to use
400
   @param [out] budget     pointer to the variable tha will contain
993 lipari 401
     the time it takes to transmitt a packet
899 trimarchi 402
 
985 julio 403
   @retval 0 if the operation is succesful
404
   @retval FSF_ERR_BAD_ARGUMENT if network_id is not a valid
993 lipari 405
     network identifier of if budget is a NULL pointer
985 julio 406
*/
993 lipari 407
int
408
fsf_packet_tx_time
409
  (fsf_network_id_t      network_id,
410
   struct timespec       *budget);
985 julio 411
 
929 lipari 412
/**
413
   \ingroup distjmodule
414
 
985 julio 415
   This operation puts in the variable pointed to by
416
   packet_size the maximum number of bytes that can be sent
417
   in a packet through the network designated by network_id.
418
   It is usually a configuration value and it helps the user
419
   application to calculate the number of packets it will
420
   need to reserve for the periodic transmision of its
421
   messages and prepare the corresponding contracts.
422
 
423
   @param [in] network_id   the identifier ot the network to use
424
   @param [out] packet_size pointer to the variable tha will contain
425
     the maximum size in bytes of a packet
426
 
427
   @retval 0 if the operation is succesful
428
   @retval FSF_ERR_BAD_ARGUMENT if network_id is not a valid
429
     network identifier of if packet_size is a NULL pointer
430
*/
431
int
432
fsf_packet_size
433
  (fsf_network_id_t      network_id,
434
   size_t               *packet_size);
435
 
436
 
437
/**
438
   \ingroup distjmodule
439
 
440
   This operation is used to obtain the maximum number of
441
   packets of which a message can be formed, for the
442
   specified network. A message is defined as the piece of
443
   information used in a send operation. Since the value
444
   returned by this operation is measured in packet units,
445
   the effective size can be calculated multiplying this
446
   value by the size of a packet.  When the value returned by
447
   this operation is larger than 1 it means the
448
   implementation will make the partition of messages into
449
   packets and its recomposition at the receiving node.
450
 
451
   @param [in] network_id    the identifier ot the network to use
452
   @param [out] max_msg_size pointer to the variable tha will contain
453
     the maximum number of packets sent in a single send operation
454
 
455
   @retval 0 if the operation is succesful
456
   @retval FSF_ERR_BAD_ARGUMENT if network_id is not a valid
457
     network identifier of if max_msg_size is a NULL pointer
458
*/
899 trimarchi 459
int
460
fsf_max_message_size
461
  (fsf_network_id_t      network_id,
462
   size_t                *max_msg_size);
463
 
464
 
985 julio 465
 
899 trimarchi 466
#endif // _FSF_DISTRIBUTED_H_