1 //----------------------------------------------------------------------
2 // Copyright (C) 2006 - 2007 by the FRESCOR consortium:
4 // Universidad de Cantabria, SPAIN
5 // University of York, UK
6 // Scuola Superiore Sant'Anna, ITALY
7 // Kaiserslautern University, GERMANY
8 // Univ. Politecnica Valencia, SPAIN
9 // Czech Technical University in Prague, CZECH REPUBLIC
11 // Thales Communication S.A. FRANCE
12 // Visual Tools S.A. SPAIN
13 // Rapita Systems Ltd UK
16 // See http://www.frescor.org
18 // The FRESCOR project (FP6/2005/IST/5-034026) is funded
19 // in part by the European Union Sixth Framework Programme
20 // The European Union is not liable of any use that may be
24 // based on previous work (FSF) done in the FIRST project
26 // Copyright (C) 2005 Mälardalen University, SWEDEN
27 // Scuola Superiore S.Anna, ITALY
28 // Universidad de Cantabria, SPAIN
29 // University of York, UK
31 // This file is part of FNA (Frescor Network Adaptation)
33 // FNA is free software; you can redistribute it and/or modify it
34 // under terms of the GNU General Public License as published by the
35 // Free Software Foundation; either version 2, or (at your option) any
36 // later version. FNA is distributed in the hope that it will be
37 // useful, but WITHOUT ANY WARRANTY; without even the implied warranty
38 // of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
39 // General Public License for more details. You should have received a
40 // copy of the GNU General Public License along with FNA; see file
41 // COPYING. If not, write to the Free Software Foundation, 675 Mass Ave,
42 // Cambridge, MA 02139, USA.
44 // As a special exception, including FNA header files in a file,
45 // instantiating FNA generics or templates, or linking other files
46 // with FNA objects to produce an executable application, does not
47 // by itself cause the resulting executable application to be covered
48 // by the GNU General Public License. This exception does not
49 // however invalidate any other reasons why the executable file might be
50 // covered by the GNU Public License.
51 // -----------------------------------------------------------------------
53 //==============================================
54 // ******** **** ** **
55 // **///// /**/** /** ****
56 // ** /**//** /** **//**
57 // ******* /** //** /** ** //**
58 // **//// /** //**/** **********
59 // ** /** //****/**//////**
60 // ** /** //***/** /**
63 // FNA(Frescor Network Adaptation layer), pronounced "efe ene a"
64 //==============================================================
69 /* for frsh_resource_id_t, frsh_contract_t, etc */
70 #include "frsh_core_types.h"
71 /* for frsh_network_address_t, frsh_stream_id_t */
72 #include "frsh_distributed_types.h"
75 /* for ERROR constants */
76 // #include "fna_error.h"
77 /* for uint32_t, UINT32_MAX */
81 * @defgroup fna FNA Private Interface
83 * FNA is a Network adaption layer that allows to plugin new
84 * network protocols to the distributed module.
86 * It is divided in two parts:
87 * - FRSH_FNA: public types and functions for the FRSH API
88 * - FNA: private functions only used within FRSH.
93 //////////////////////////////////////////////////////////////////////
95 //////////////////////////////////////////////////////////////////////
98 * @defgroup fnainit FNA Initialization
101 * These functions need to be called before using any network
109 * This function will be hooked to the frsh_init function and it is
110 * intented to initialize the protocol and its structures.
112 * @param[in] resource_id The network we are referring to (a protocol
113 * could be able to handle several networks at the same time)
116 * 0 if there are no errors \n
117 * FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
118 * FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
119 * FNA_ERR_ALREADY_INITIALIZED:
120 * if the function has already been called before (with success) \n
123 typedef int fna_init_t(const frsh_resource_id_t resource_id);
127 ///////////////////////////////////////////////////////////////////
129 ///////////////////////////////////////////////////////////////////
132 * @defgroup fnavres FNA Virtual Resources
135 * The following functions are used to negotiate, renegotiate and cancel
136 * virtual network resources.
144 * Internal virtual resource id. In the current implementation it is a 16 bits
145 * value (up to 65536 vres) so it can be integrated easily with the
146 * frsh_vres_id_t type (see frsh_internal_data.h)
149 typedef uint16_t fna_vres_id_t;
152 * fna_contract_negotiate()
154 * The operation negotiates a contract and if accepted it will return
155 * a fna_vres_id_t. It will also check that the given contract_id is unique
156 * within the network.
158 * If the on-line admission test is enabled, it determines whether the
159 * contract can be admitted or not based on the current contracts
160 * established in the network. Then it creates the vres and
161 * recalculates all necessary parameters for the contracts already
162 * present in the system.
164 * This is a potentially blocking operation, it returns when the
165 * system has either rejected the contract, or admitted it and made it
168 * @param[in] resource_id The network we are referring to (a protocol
169 * could be able to handle several networks at the same time)
170 * @param[in] contract The contract parameters to negotiate
171 * @param[out] vres The internal virtual resource id
174 * 0 if there are no errors (in this case it also means contract accepted) \n
175 * FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
176 * FNA_ERR_TOO_MANY_VRES: if there is no space for more vres \n
177 * FNA_ERR_CONTRACT_ID_ALREADY_EXISTS: contract_id is not unique \n
178 * FNA_ERR_CONTRACT_REJECTED: if the contract is not accepted \n
179 * FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
180 * FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
181 * FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
184 typedef int fna_contract_negotiate_t
185 (const frsh_resource_id_t resource_id,
186 const frsh_contract_t *contract,
187 fna_vres_id_t *vres);
190 * fna_contract_renegotiate_sync()
192 * The operation renegotiates a contract for an existing vres. If
193 * the on-line admission test is enabled it determines whether the
194 * contract can be admitted or not based on the current contracts
195 * established in the system. If it cannot be admitted, the old
196 * contract remains in effect and an error is returned. If it can be
197 * admitted, it recalculates all necessary parameters for the
198 * contracts already present in the system and returns zero. This is a
199 * potentially blocking operation; it returns when the system has
200 * either rejected the new contract, or admitted it and made it
203 * @param[in] resource_id The network we are referring to (a protocol
204 * could be able to handle several networks at the same time)
205 * @param[in] vres The internal virtual resource id to renegotiate
206 * @param[in] new_contract The new contract
209 * 0 if there are no errors (in this case it also means contract accepted) \n
210 * FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
211 * FNA_ERR_NOT_CONTRACTED_VRES: if the vres is not contracted \n
212 * FNA_ERR_CONTRACT_ID_ALREADY_EXISTS: contract_id is not unique \n
213 * FNA_ERR_CONTRACT_REJECTED: if the contract is not accepted \n
214 * FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
215 * FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
216 * FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
219 typedef int fna_contract_renegotiate_sync_t
220 (const frsh_resource_id_t resource_id,
221 const fna_vres_id_t vres,
222 const frsh_contract_t *new_contract);
225 * fna_contract_renegotiate_async()
227 * The operation enqueues a renegotiate operation for an existing
228 * vres, and returns immediately. The renegotiate operation is
229 * performed asynchronously, as soon as it is practical; meanwhile the
230 * system operation will continue normally. When the renegotiation is
231 * made, if the on-line admission test is enabled it determines
232 * whether the contract can be admitted or not based on the current
233 * contracts established in the system. If it cannot be admitted, the
234 * old contract remains in effect. If it can be admitted, it
235 * recalculates all necessary parameters for the contracts already
236 * present in the system.
238 * When the operation is completed, notification is made to the
239 * caller, if requested, via a signal. The status of the operation (in
240 * progress, admitted, rejected) can be checked with the
241 * frsh_vres_get_renegotiation_status() operation. The argument
242 * sig_notify can be FRSH_NULL_SIGNAL (no notification), or any FRSH
243 * signal value and in this case signal_info is to be sent with the signal.
245 * @param[in] resource_id The network we are referring to (a protocol
246 * could be able to handle several networks at the same time)
247 * @param[in] vres The internal virtual resource id to renegotiate
248 * @param[in] new_contract The new contract
249 * @param[in] signal_to_notify Signal number to use to notify vres of
250 * the negotiation result. If FRSH_NULL_SIGNAL, no signal will be raised.
251 * @param[in] signal_info: Associated info that will come with the signal.
252 * This parameter will be ignored if signal_to_notify == FRSH_NULL_SIGNAL.
255 * 0 if there are no errors \n
256 * FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
257 * FNA_ERR_NOT_CONTRACTED_VRES: if the vres is not contracted \n
258 * FNA_ERR_CONTRACT_ID_ALREADY_EXISTS: contract_id is not unique \n
259 * FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
260 * FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
261 * FNA_ERR_BAD_ARGUMENT: if pointers are NULL, or sig_notify is neither
262 * NULL nor a valid POSIX signal \n
265 typedef int fna_contract_renegotiate_async_t
266 (const frsh_resource_id_t resource_id,
267 const fna_vres_id_t vres,
268 const frsh_contract_t *new_contract,
269 frsh_signal_t signal_to_notify,
270 frsh_signal_info_t signal_info);
273 * fna_vres_get_renegotiation_status()
275 * The operation reports on the status of the last renegotiation
276 * operation enqueued for the specified vres. It is callable even
277 * after notification of the completion of such operation, if
280 * If the vres is not and has not been involved in any of the
281 * frsh_contract_renegotiate_async() or frsh_group_change_mode_async()
282 * operations, the status returned is FNA_NOT_REQUESTED
284 * @param[in] resource_id The network we are referring to (a protocol
285 * could be able to handle several networks at the same time)
286 * @param[in] vres The internal virtual resource id we want the status from
287 * @param[in] renegotiation_status The status of the last renegotiation on
288 * vres (FRSH_RS_IN_PROGRESS, FRSH_RS_REJECTED, FRSH_RS_ADMITTED,
289 * FRSH_RS_NOT_REQUESTED)
292 * 0 if there are no errors \n
293 * FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
294 * FNA_ERR_NOT_CONTRACTED_VRES: if the vres is not contracted \n
295 * FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
296 * FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
297 * FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
300 typedef int fna_vres_get_renegotiation_status_t
301 (const frsh_resource_id_t resource_id,
302 const fna_vres_id_t vres,
303 frsh_renegotiation_status_t *renegotiation_status);
308 * The operation eliminates the specified vres
309 * and recalculates all necessary parameters for the contracts
310 * remaining in the system. This is a potentially blocking operation;
311 * it returns when the system has made the changes effective.
313 * @param[in] resource_id The network we are referring to (a protocol
314 * could be able to handle several networks at the same time)
315 * @param[in] vres The internal virtual resource id to destroy
318 * 0 if there are no errors \n
319 * FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
320 * FNA_ERR_NOT_CONTRACTED_VRES: if the vres is not contracted \n
321 * FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
322 * FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
323 * FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
326 typedef int fna_vres_destroy_t
327 (const frsh_resource_id_t resource_id,
328 const fna_vres_id_t vres);
331 * fna_vres_get_contract()
333 * This operation stores the contract parameters currently associated
334 * with the specified vres in the variable pointed to by
335 * contract. It returns an error if the vres_id is not recognised.
337 * @param[in] resource_id The network we are referring to (a protocol
338 * could be able to handle several networks at the same time)
339 * @param[in] vres The internal virtual resource id
340 * @param[out] contract The contract parameters that we want
343 * 0 if there are no errors \n
344 * FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
345 * FNA_ERR_NOT_CONTRACTED_VRES: if the vres is not contracted \n
346 * FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
347 * FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
348 * FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
351 typedef int fna_vres_get_contract_t
352 (const frsh_resource_id_t resource_id,
353 const fna_vres_id_t vres,
354 frsh_contract_t *contract);
357 * fna_vres_get_usage()
359 * This function gets the execution time spent by all messages that have been
360 * sent through the specified vres.
362 * @param[in] resource_id The network we are referring to (a protocol
363 * could be able to handle several networks at the same time)
364 * @param[in] vres The internal virtual resource id
365 * @param[out] usage Execution time spent by this vres
368 * 0 if there are no errors \n
369 * FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
370 * FNA_ERR_NOT_CONTRACTED_VRES: if the vres is not contracted \n
371 * FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
372 * FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
373 * FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
376 typedef int fna_vres_get_usage_t
377 (const frsh_resource_id_t resource_id,
378 const fna_vres_id_t vres,
379 struct timespec *usage);
382 * fna_vres_get_remaining_budget()
384 * This function stores in the variable pointed to by budget the
385 * remaining execution-time budget associated with the specified
386 * vres in the present period.
388 * @param[in] resource_id The network we are referring to (a protocol
389 * could be able to handle several networks at the same time)
390 * @param[in] vres The internal virtual resource id
391 * @param[out] remaining_budget The remaining budget for this period
394 * 0 if there are no errors \n
395 * FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
396 * FNA_ERR_NOT_CONTRACTED_VRES: if the vres is not contracted \n
397 * FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
398 * FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
399 * FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
402 typedef int fna_vres_get_remaining_budget_t
403 (const frsh_resource_id_t resource_id,
404 const fna_vres_id_t vres,
405 struct timespec *remaining_budget);
408 * fna_vres_get_budget_and_period()
410 * This function gets the budget and period associated with the specified vres
411 * for each period. If one of these pointers is NULL, the corresponding
412 * information is not stored.
414 * @param[in] resource_id The network we are referring to (a protocol
415 * could be able to handle several networks at the same time)
416 * @param[in] vres The internal virtual resource id
417 * @param[out] budget The budget associated to vres
418 * @param[out] period The period associated to vres
421 * 0 if there are no errors \n
422 * FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
423 * FNA_ERR_NOT_CONTRACTED_VRES: if the vres is not contracted \n
424 * FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
425 * FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
426 * FNA_ERR_BAD_ARGUMENT: if both pointers are NULL \n
429 typedef int fna_vres_get_budget_and_period_t
430 (const frsh_resource_id_t resource_id,
431 const fna_vres_id_t vres,
432 struct timespec *budget,
433 struct timespec *period);
437 ///////////////////////////////////////////////////////////////////
438 // SPARE CAPACITY FUNCIONS
439 ///////////////////////////////////////////////////////////////////
442 * @defgroup fnaspare FNA Spare Capacity
445 * The following functions are used to get spare capacity data
451 * fna_resource_get_capacity()
453 * This operation gets the spare capacity currently assigned to a importance
454 * level. If we divide this value by UINT32_MAX we will get the network
455 * utilization associated to the spare capacity of a importance level.
457 * The following is typically in stdint.h: \n
458 * - typedef unsigned int uint32_t; \n
459 * - # define UINT32_MAX (4294967295U) \n
461 * @param[in] resource_id The network we are referring to (a protocol
462 * could be able to handle several networks at the same time)
463 * @param[in] importance The importance we want the capacity of
464 * @param[out] capacity The spare capacity for that importance level
467 * 0 if there are no errors \n
468 * FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
469 * FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
470 * FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
471 * FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
474 typedef int fna_resource_get_capacity_t
475 (const frsh_resource_id_t resource_id,
476 const int importance,
480 * fna_resource_get_total_weight()
482 * This function gets the sum of the weight parameters for all vres in a
483 * network of an importance level.
485 * @param[in] resource_id The network we are referring to (a protocol
486 * could be able to handle several networks at the same time)
487 * @param[in] importance The importance we want the total weight of
488 * @param[out] total_weight The total weight for that importance level
491 * 0 if there are no errors \n
492 * FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
493 * FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
494 * FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
495 * FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
498 typedef int fna_resource_get_total_weight_t
499 (const frsh_resource_id_t resource_id,
500 const int importance,
504 * fna_vres_decrease_capacity()
506 * This function allows to ask for less budget and period than what we
507 * received. The request must be compatible with the rest of contract
508 * parameters of the vres. If we want to recover the released capacity
509 * we will need to renegotiate.
511 * @param[in] resource_id The network we are referring to (a protocol
512 * could be able to handle several networks at the same time)
513 * @param[in] vres The internal virtual resource id
514 * @param[in] new_budget The new_budget
515 * @param[in] new_period The new Period
518 * 0 if there are no errors \n
519 * FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
520 * FNA_ERR_NOT_CONTRACTED_VRES: if the vres is not contracted \n
521 * FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
522 * FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
523 * FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
524 * FNA_ERR_CONTRACT_REJECTED: if it is incompatible with the current
528 typedef int fna_vres_decrease_capacity_t
529 (const frsh_resource_id_t resource_id,
530 const fna_vres_id_t vres,
531 const struct timespec new_budget,
532 const struct timespec new_period);
536 ///////////////////////////////////////////////////////////////////
537 // SEND RECEIVE OPERATIONS
538 ///////////////////////////////////////////////////////////////////
541 * @defgroup fnasendrecv FNA Send and Receive
544 * The following functions are used to send and receive
550 FRSH_SEND_ENDPOINT_TYPE,
551 FRSH_RECEIVE_ENDPOINT_TYPE
552 } frsh_endpoint_type_t;
555 frsh_endpoint_type_t endpoint_type; // send_endpoint or receive_endpoint
556 fna_vres_id_t vres; // only for send_endpoints
557 bool is_bound; // only for send_endpoints
558 frsh_network_address_t destination; // only for send_endpoints
559 frsh_resource_id_t resource_id;
560 frsh_stream_id_t stream_id;
561 frsh_protocol_info_t protocol_info;
562 frsh_endpoint_queueing_info_t queue_info;
564 frsh_send_endpoint_protocol_info_t send;
565 frsh_receive_endpoint_protocol_info_t receive;
566 } endpoint_protocol_info;
567 } fna_endpoint_data_t;
572 * Similar to previous function but now the sending thread gets blocked
573 * until the message is already sent to the network.
575 * @param[in] endpoint The send endpoint we are sending through. It must
576 * be bound to a virtual resource (resource_id is in the endpoint).
577 * @param[in] msg The message we want to send
578 * @param[in] size The size in bytes of the message
581 * 0 if there are no errors \n
582 * FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
583 * FNA_ERR_NOT_BOUND: if endpoint is not bound to a valid vres \n
584 * FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
585 * FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
586 * FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
587 * FNA_ERR_TOO_LARGE: if the message is too large for the network protocol \n
588 * FNA_ERR_BUFFER_FULL: if the message has been discarded because
589 * the queue is full (and does not have the policy FNA_QP_OLDEST) \n
592 typedef int fna_send_sync_t
593 (const fna_endpoint_data_t *endpoint,
600 * This operation sends a message stored in msg and of length size
601 * through the given send endpoint. The operation is non-blocking and
602 * returns immediately.
604 * @param[in] endpoint The send endpoint we are sending through. It must
605 * be bound to a virtual resource (resource_id is in the endpoint).
606 * @param[in] msg The message we want to send
607 * @param[in] size The size in bytes of the message
610 * 0 if there are no errors \n
611 * FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
612 * FNA_ERR_NOT_BOUND: if endpoint is not bound to a valid vres \n
613 * FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
614 * FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
615 * FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
616 * FNA_ERR_TOO_LARGE: if the message is too large for the network protocol \n
617 * FNA_ERR_BUFFER_FULL: if the message has been discarded because
618 * the queue is full (and does not have the policy FNA_QP_OLDEST) \n
621 typedef int fna_send_async_t
622 (const fna_endpoint_data_t *endpoint,
629 * This operation is used to receive messages from the network with a
630 * blocking behavior (if there are no messages this operation blocks
631 * the calling thread).
633 * When a message is available, it is copied to buffer (up to its size).
634 * The number of bytes copied is returned in received_bytes. The rest
635 * of the bytes of that message will be lost or not depending on the
636 * protocol (FNA_ERR_NO_SPACE will be returned if it is).
638 * The function fails with FNA_ERR_NO_SPACE if the buffersize is
639 * too small for the message received. In this case the message is
642 * Messages arriving at a receiver buffer that is full will be handled
643 * according to the queueing policy of the endpoint (overwrite oldest,
646 * @param[in] endpoint The receive endpoint we are receiving from.
647 * (resource_id is in the endpoint).
648 * @param[out] buffer Buffer for storing the received message
649 * @param[in] buffer_size The size in bytes of this buffer
650 * @param[out] received_bytes The actual number of received bytes
651 * @param[out] from Address of the sender node
654 * 0 if there are no errors \n
655 * FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
656 * FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
657 * FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
658 * FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
659 * FNA_ERR_NO_SPACE: if the message size is bigger than the
660 * provided buffer. \n
663 typedef int fna_receive_sync_t
664 (const fna_endpoint_data_t *endpoint,
666 const size_t buffer_size,
667 size_t *received_bytes,
668 frsh_network_address_t *from);
671 * fna_receive_async()
673 * This operation is similar to the previous one but it works in a non
674 * blocking (asynchronous) fashion. If no message is available it
675 * returns with error FNA_NO_MESSAGE.
677 * @param[in] endpoint The receive endpoint we are receiving from.
678 * (resource_id is in the endpoint).
679 * @param[out] buffer Buffer for storing the received message
680 * @param[in] buffer_size The size in bytes of this buffer
681 * @param[out] received_bytes The actual number of received bytes
682 * @param[out] from Address of the sender node
685 * 0 if there are no errors \n
686 * FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
687 * FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
688 * FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
689 * FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
690 * FNA_ERR_NO_SPACE: if the message size is bigger than the
691 * provided buffer. \n
692 * FNA_NO_MESSAGE: if no messages are available in the queue. \n
695 typedef int fna_receive_async_t
696 (const fna_endpoint_data_t *endpoint,
698 const size_t buffer_size,
699 size_t *received_bytes,
700 frsh_network_address_t *from);
703 * fna_send_endpoint_get_status()
705 * This function tells the number of messages still pending in the
706 * endpoint queue, whether the network is up or down with some
707 * optional information which is protocol_dependent.
709 * @param[in] endpoint The send endpoint (resource_id is in the endpoint).
710 * @param[out] number_of_pending_messages The number of pending messages
711 * @param[out] network_status How is the network (up, down..)
712 * @param[out] protocol_status Protocol dependent status info
715 * 0 if there are no errors \n
716 * FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
717 * FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
718 * FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
719 * FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
722 typedef int fna_send_endpoint_get_status_t
723 (const fna_endpoint_data_t *endpoint,
724 int *number_of_pending_messages,
725 frsh_endpoint_network_status_t *network_status,
726 frsh_protocol_status_t *protocol_status);
729 * fna_receive_endpoint_create_callback()
731 * This operation is a called from frsh_receive_endpoint_create with a
732 * receive_endpoint structure already filled.
734 * Receiving endpoints are not bound to any network vres, this is
735 * because don't originate any traffic.
737 * @param[in] endpoint the endpoint object.
740 * 0 if there are no errors \n
741 * FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
742 * FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
743 * FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
744 * FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
746 typedef int fna_receive_endpoint_create_callback_t
747 (const fna_endpoint_data_t *endpoint);
750 * fna_receive_endpoint_get_pending_messages
752 * This function tells the number of messages still pending in the
753 * endpoint queue, whether the network is up or down and some optional
754 * information which is protocol dependent.
756 * @param[in] endpoint The receive endpoint (resource_id is in the endpoint).
757 * @param[out] number_of_pending_messages The number of pending messages
758 * @param[out] network_status How is the network (up, down..)
759 * @param[out] protocol_status Protocol dependent status info
762 * 0 if there are no errors \n
763 * FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
764 * FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
765 * FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
766 * FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
769 typedef int fna_receive_endpoint_get_status_t
770 (const fna_endpoint_data_t *endpoint,
771 int *number_of_pending_messages,
772 frsh_endpoint_network_status_t *network_status,
773 frsh_protocol_status_t *protocol_status);
777 //////////////////////////////////////////////////////////////////////
778 // NETWORK CONFIGURATION FUNCTIONS
779 //////////////////////////////////////////////////////////////////////
782 * @defgroup frshfnaconfig FNA Network Configuration
785 * These functions are needed to set/get some network dependent values
791 * fna_network_get_max_message_size()
793 * This operation gives the maximum number of bytes that can be sent
794 * at a time through the send function when using the network designated by
795 * 'resource_id' and sending it to 'destination'.
797 * If the application needs to send bigger messages it will have to
800 * Some protocols, like IP, are capable of sending large messages
801 * (and use fragmentation internally) but other protocols don't.
803 * @param[in] resource_id The network we want the tx time from.
804 * @param[in] destination The destination address
805 * @param[out] max_size The maximum number of bytes for each message
808 * 0 if there are no errors \n
809 * FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
810 * FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
811 * FNA_ERR_RESOURCE_ID_INVALID: if resource id does not represent
812 * a network accessible from the current processing node \n
813 * FNA_ERR_BAD_ARGUMENT: if pointers are NULL or destination is
817 typedef int fna_network_get_max_message_size_t
818 (const frsh_resource_id_t resource_id,
819 const frsh_network_address_t destination,
823 * fna_network_bytes_to_budget()
825 * This operation converts a number of bytes into a temporal budget for
826 * a specific network. Network overheads are not included here but are
827 * considered internally when negotiating a specific contract.
829 * @param[in] resource_id The network
830 * @param[in] nbytes Number of bytes
831 * @param[out] budget The network budget for nbytes
834 * 0 if there are no errors \n
835 * FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
836 * FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
837 * FNA_ERR_RESOURCE_ID_INVALID: if resource id does not represent
838 * a network accessible from the current processing node \n
839 * FNA_ERR_BAD_ARGUMENT: if pointers are NULL or nbytes is less
843 typedef int fna_network_bytes_to_budget_t
844 (const frsh_resource_id_t resource_id,
846 struct timespec *budget);
849 * fna_network_budget_to_bytes()
851 * This operation converts a temporal budget into a number of bytes for
852 * a specific network. Network overheads are not included.
854 * @param[in] resource_id The network
855 * @param[in] budget The network budget for nbytes
856 * @param[out] nbytes Number of bytes
859 * 0 if there are no errors \n
860 * FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
861 * FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
862 * FNA_ERR_RESOURCE_ID_INVALID: if resource id does not represent
863 * a network accessible from the current processing node \n
864 * FNA_ERR_BAD_ARGUMENT: if pointers are NULL or budget refers to
865 * an invalid time value \n
868 typedef int fna_network_budget_to_bytes_t
869 (const frsh_resource_id_t resource_id,
870 const struct timespec *budget,
874 * fna_network_get_min_effective_budget()
876 * This operation gets the minimum effective budget for a network. Each message
877 * consumes a contracted budget in "chunks" (i.e: packets) that we call
878 * minimum effective budget.
880 * A negotiated contract, for N bytes in a period T, means that there is a
881 * virtual resource that reserves for the user:
883 * Ceiling ((N bytes) / budget_to_bytes (min_effective_budget)) "CHUNKS"
885 * Note that if the user decides not to send these N bytes at once but, say,
886 * one byte at a time, it will consume one "CHUNK" at a time and the reserved
887 * budget will become exhausted before sending all the bytes.
889 * @param[in] resource_id The network
890 * @param[out] budget The network budget
893 * 0 if there are no errors \n
894 * FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
895 * FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
896 * FNA_ERR_RESOURCE_ID_INVALID: if resource id does not represent
897 * a network accessible from the current processing node \n
898 * FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
901 typedef int fna_network_get_min_effective_budget_t
902 (const frsh_resource_id_t resource_id,
903 struct timespec *budget);
908 fna_init_t *fna_init;
909 fna_contract_negotiate_t *fna_contract_negotiate;
910 fna_contract_renegotiate_sync_t *fna_contract_renegotiate_sync;
911 fna_contract_renegotiate_async_t *fna_contract_renegotiate_async;
912 fna_vres_get_renegotiation_status_t *fna_vres_get_renegotiation_status;
913 fna_vres_destroy_t *fna_vres_destroy;
914 fna_vres_get_contract_t *fna_vres_get_contract;
915 fna_vres_get_usage_t *fna_vres_get_usage;
916 fna_vres_get_remaining_budget_t *fna_vres_get_remaining_budget;
917 fna_vres_get_budget_and_period_t *fna_vres_get_budget_and_period;
918 fna_resource_get_capacity_t *fna_resource_get_capacity;
919 fna_resource_get_total_weight_t *fna_resource_get_total_weight;
920 fna_vres_decrease_capacity_t *fna_vres_decrease_capacity;
921 fna_send_sync_t *fna_send_sync;
922 fna_send_async_t *fna_send_async;
923 fna_receive_sync_t *fna_receive_sync;
924 fna_receive_async_t *fna_receive_async;
925 fna_send_endpoint_get_status_t *fna_send_endpoint_get_status;
926 fna_receive_endpoint_create_callback_t *fna_receive_endpoint_created;
927 fna_receive_endpoint_get_status_t *fna_receive_endpoint_get_status;
928 fna_network_get_max_message_size_t *fna_network_get_max_message_size;
929 fna_network_bytes_to_budget_t *fna_network_bytes_to_budget;
930 fna_network_budget_to_bytes_t *fna_network_budget_to_bytes;
931 fna_network_get_min_effective_budget_t *fna_network_get_min_eff_budget;