Subversion Repositories shark

Rev

Rev 993 | Details | Compare with Previous | Last modification | View Log | RSS feed

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