include/fna.h

   1 //----------------------------------------------------------------------
   2 //  Copyright (C) 2006 - 2007 by the FRESCOR consortium:
   3 //
   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
  10 //    ENEA                                   SWEDEN
  11 //    Thales Communication S.A.              FRANCE
  12 //    Visual Tools S.A.                      SPAIN
  13 //    Rapita Systems Ltd                     UK
  14 //    Evidence                               ITALY
  15 //
  16 //    See http://www.frescor.org
  17 //
  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
  21 //        made of this code.
  22 //
  23 //
  24 //  based on previous work (FSF) done in the FIRST project
  25 //
  26 //   Copyright (C) 2005  Mälardalen University, SWEDEN
  27 //                       Scuola Superiore S.Anna, ITALY
  28 //                       Universidad de Cantabria, SPAIN
  29 //                       University of York, UK
  30 //
  31 // This file is part of FNA (Frescor Network Adaptation)
  32 //
  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.
  43 //
  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 // -----------------------------------------------------------------------
  52
  53 //==============================================
  54 //  ******** ****     **     **
  55 //  **///// /**/**   /**    ****
  56 //  **      /**//**  /**   **//**
  57 //  ******* /** //** /**  **  //**
  58 //  **////  /**  //**/** **********
  59 //  **      /**   //****/**//////**
  60 //  **      /**    //***/**     /**
  61 //  /       //      /// //      //
  62 //
  63 // FNA(Frescor Network Adaptation layer), pronounced "efe ene a"
  64 //==============================================================
  65
  66 #ifndef _FNA_H_
  67 #define _FNA_H_
  68
  69 /* for frsh_resource_id_t, frsh_contract_t, for frsh_network_address_t,
  70    frsh_stream_id_t, ... */
  71 #include "frsh.h"
  72 /* for timespec */
  73 #include <time.h>
  74 /* for ERROR constants */
  75 // #include "fna_error.h"
  76 /* for uint32_t, UINT32_MAX */
  77 #include <stdint.h>
  78
  79 /**
  80  * @defgroup fna FNA Private Interface
  81  *
  82  * FNA is a Network adaption layer that allows to plugin new
  83  * network protocols to the distributed module.
  84  *
  85  * It is divided in two parts:
  86  *  - FRSH_FNA:  public types and functions for the FRSH API
  87  *  - FNA: private functions only used within FRSH.
  88  *
  89  **/
  90
  91
  92 //////////////////////////////////////////////////////////////////////
  93 //           INITIALIZATION
  94 //////////////////////////////////////////////////////////////////////
  95
  96 /**
  97  * @defgroup fnainit FNA Initialization
  98  * @ingroup fna
  99  *
 100  * These functions need to be called before using any network
 101  *
 102  * @{
 103  **/
 104
 105 /**
 106  * fna_init()
 107  *
 108  * This function will be hooked to the frsh_init function and it is
 109  * intented to initialize the protocol and its structures.
 110  *
 111  * @param[in]  resource_id The network we are referring to (a protocol
 112  * could be able to handle several networks at the same time)
 113  *
 114  * @return
 115  *   0 if there are no errors \n
 116  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 117  *   FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
 118  *   FNA_ERR_ALREADY_INITIALIZED:
 119  *      if the function has already been called before (with success) \n
 120  *
 121  **/
 122 typedef int fna_init_t(const frsh_resource_id_t resource_id);
 123
 124 /*@}*/
 125
 126 ///////////////////////////////////////////////////////////////////
 127 //           VIRTUAL RESOURCES
 128 ///////////////////////////////////////////////////////////////////
 129
 130 /**
 131  * @defgroup fnavres FNA Virtual Resources
 132  * @ingroup fna
 133  *
 134  * The following functions are used to negotiate, renegotiate and cancel
 135  * virtual network resources.
 136  *
 137  * @{
 138  **/
 139
 140 /**
 141  * fna_vres_id_t
 142  *
 143  * Internal virtual resource id. In the current implementation it is a 16 bits
 144  * value (up to 65536 vres) so it can be integrated easily with the
 145  * frsh_vres_id_t type (see frsh_internal_data.h)
 146  *
 147  **/
 148 typedef uint16_t fna_vres_id_t;
 149
 150 /**
 151  * fna_contract_negotiate()
 152  *
 153  * The operation negotiates a contract and if accepted it will return
 154  * a fna_vres_id_t. It will also check that the given contract_id is unique
 155  * within the network.
 156  *
 157  * If the on-line admission test is enabled, it determines whether the
 158  * contract can be admitted or not based on the current contracts
 159  * established in the network. Then it creates the vres and
 160  * recalculates all necessary parameters for the contracts already
 161  * present in the system.
 162  *
 163  * This is a potentially blocking operation, it returns when the
 164  * system has either rejected the contract, or admitted it and made it
 165  * effective.
 166  *
 167  * @param[in] resource_id The network we are referring to (a protocol
 168  * could be able to handle several networks at the same time)
 169  * @param[in] contract  The contract parameters to negotiate
 170  * @param[out] vres The internal virtual resource id
 171  *
 172  * @return
 173  *   0 if there are no errors (in this case it also means contract accepted) \n
 174  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 175  *   FNA_ERR_TOO_MANY_VRES: if there is no space for more vres \n
 176  *   FNA_ERR_CONTRACT_ID_ALREADY_EXISTS: contract_id is not unique \n
 177  *   FNA_ERR_CONTRACT_REJECTED: if the contract is not accepted \n
 178  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 179  *   FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
 180  *   FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
 181  *
 182  **/
 183 typedef int fna_contract_negotiate_t
 184    (const frsh_resource_id_t resource_id,
 185     const frsh_contract_t *contract,
 186     fna_vres_id_t *vres);
 187
 188 /**
 189  * fna_contract_renegotiate_sync()
 190  *
 191  * The operation renegotiates a contract for an existing vres. If
 192  * the on-line admission test is enabled it determines whether the
 193  * contract can be admitted or not based on the current contracts
 194  * established in the system. If it cannot be admitted, the old
 195  * contract remains in effect and an error is returned. If it can be
 196  * admitted, it recalculates all necessary parameters for the
 197  * contracts already present in the system and returns zero. This is a
 198  * potentially blocking operation; it returns when the system has
 199  * either rejected the new contract, or admitted it and made it
 200  * effective.
 201  *
 202  * @param[in] resource_id The network we are referring to (a protocol
 203  * could be able to handle several networks at the same time)
 204  * @param[in] vres The internal virtual resource id to renegotiate
 205  * @param[in] new_contract The new contract
 206  *
 207  *  @return
 208  *   0 if there are no errors (in this case it also means contract accepted) \n
 209  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 210  *   FNA_ERR_NOT_CONTRACTED_VRES: if the vres is not contracted \n
 211  *   FNA_ERR_CONTRACT_ID_ALREADY_EXISTS: contract_id is not unique \n
 212  *   FNA_ERR_CONTRACT_REJECTED: if the contract is not accepted \n
 213  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 214  *   FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
 215  *   FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
 216  *
 217  **/
 218 typedef int fna_contract_renegotiate_sync_t
 219    (const frsh_resource_id_t resource_id,
 220     const fna_vres_id_t vres,
 221     const frsh_contract_t *new_contract);
 222
 223 /**
 224  * fna_contract_renegotiate_async()
 225  *
 226  * The operation enqueues a renegotiate operation for an existing
 227  * vres, and returns immediately. The renegotiate operation is
 228  * performed asynchronously, as soon as it is practical; meanwhile the
 229  * system operation will continue normally. When the renegotiation is
 230  * made, if the on-line admission test is enabled it determines
 231  * whether the contract can be admitted or not based on the current
 232  * contracts established in the system. If it cannot be admitted, the
 233  * old contract remains in effect. If it can be admitted, it
 234  * recalculates all necessary parameters for the contracts already
 235  * present in the system.
 236  *
 237  * When the operation is completed, notification is made to the
 238  * caller, if requested, via a signal. The status of the operation (in
 239  * progress, admitted, rejected) can be checked with the
 240  * frsh_vres_get_renegotiation_status() operation.  The argument
 241  * sig_notify can be FRSH_NULL_SIGNAL (no notification), or any FRSH
 242  * signal value and in this case signal_info is to be sent with the signal.
 243  *
 244  * @param[in] resource_id The network we are referring to (a protocol
 245  * could be able to handle several networks at the same time)
 246  * @param[in] vres The internal virtual resource id to renegotiate
 247  * @param[in] new_contract The new contract
 248  * @param[in] signal_to_notify  Signal number to use to notify vres of
 249  * the negotiation result. If FRSH_NULL_SIGNAL,  no signal will be raised.
 250  * @param[in] signal_info: Associated info that will come with the signal.
 251  * This parameter will be ignored if signal_to_notify == FRSH_NULL_SIGNAL.
 252  *
 253  * @return
 254  *   0 if there are no errors \n
 255  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 256  *   FNA_ERR_NOT_CONTRACTED_VRES: if the vres is not contracted \n
 257  *   FNA_ERR_CONTRACT_ID_ALREADY_EXISTS: contract_id is not unique \n
 258  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 259  *   FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
 260  *   FNA_ERR_BAD_ARGUMENT: if pointers are NULL, or sig_notify is neither
 261  *      NULL nor a valid POSIX signal \n
 262  *
 263  **/
 264 typedef int fna_contract_renegotiate_async_t
 265    (const frsh_resource_id_t resource_id,
 266     const fna_vres_id_t vres,
 267     const frsh_contract_t *new_contract,
 268     frsh_signal_t signal_to_notify,
 269     frsh_signal_info_t signal_info);
 270
 271 /**
 272  * fna_vres_get_renegotiation_status()
 273  *
 274  * The operation reports on the status of the last renegotiation
 275  * operation enqueued for the specified vres. It is callable even
 276  * after notification of the completion of such operation, if
 277  * requested.
 278  *
 279  * If the vres is not and has not been involved in any of the
 280  * frsh_contract_renegotiate_async() or frsh_group_change_mode_async()
 281  * operations, the status returned is FNA_NOT_REQUESTED
 282  *
 283  * @param[in] resource_id The network we are referring to (a protocol
 284  * could be able to handle several networks at the same time)
 285  * @param[in] vres The internal virtual resource id we want the status from
 286  * @param[in] renegotiation_status The status of the last renegotiation on
 287  * vres (FRSH_RS_IN_PROGRESS, FRSH_RS_REJECTED, FRSH_RS_ADMITTED,
 288  * FRSH_RS_NOT_REQUESTED)
 289  *
 290  * @return
 291  *   0 if there are no errors \n
 292  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 293  *   FNA_ERR_NOT_CONTRACTED_VRES: if the vres is not contracted \n
 294  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 295  *   FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
 296  *   FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
 297  *
 298  **/
 299 typedef int fna_vres_get_renegotiation_status_t
 300    (const frsh_resource_id_t resource_id,
 301     const fna_vres_id_t vres,
 302     frsh_renegotiation_status_t *renegotiation_status);
 303
 304 /**
 305  * fna_vres_destroy()
 306  *
 307  * The operation eliminates the specified vres
 308  * and recalculates all necessary parameters for the contracts
 309  * remaining in the system. This is a potentially blocking operation;
 310  * it returns when the system has made the changes effective.
 311  *
 312  * @param[in] resource_id The network we are referring to (a protocol
 313  * could be able to handle several networks at the same time)
 314  * @param[in] vres The internal virtual resource id to destroy
 315  *
 316  * @return
 317  *   0 if there are no errors \n
 318  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 319  *   FNA_ERR_NOT_CONTRACTED_VRES: if the vres is not contracted \n
 320  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 321  *   FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
 322  *   FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
 323  *
 324  **/
 325 typedef int fna_vres_destroy_t
 326    (const frsh_resource_id_t resource_id,
 327     const fna_vres_id_t vres);
 328
 329 /**
 330  * fna_vres_get_contract()
 331  *
 332  * This operation stores the contract parameters currently associated
 333  * with the specified vres in the variable pointed to by
 334  * contract. It returns an error if the vres_id is not recognised.
 335  *
 336  * @param[in] resource_id The network we are referring to (a protocol
 337  * could be able to handle several networks at the same time)
 338  * @param[in] vres The internal virtual resource id
 339  * @param[out] contract  The contract parameters that we want
 340  *
 341  * @return
 342  *   0 if there are no errors \n
 343  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 344  *   FNA_ERR_NOT_CONTRACTED_VRES: if the vres is not contracted \n
 345  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 346  *   FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
 347  *   FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
 348  *
 349  **/
 350 typedef int fna_vres_get_contract_t
 351    (const frsh_resource_id_t resource_id,
 352     const fna_vres_id_t vres,
 353     frsh_contract_t *contract);
 354
 355 /**
 356  * fna_vres_get_usage()
 357  *
 358  * This function gets the execution time spent by all messages that have been
 359  * sent through the specified vres.
 360  *
 361  * @param[in] resource_id The network we are referring to (a protocol
 362  * could be able to handle several networks at the same time)
 363  * @param[in] vres The internal virtual resource id
 364  * @param[out] usage  Execution time spent by this vres
 365  *
 366  * @return
 367  *   0 if there are no errors \n
 368  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 369  *   FNA_ERR_NOT_CONTRACTED_VRES: if the vres is not contracted \n
 370  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 371  *   FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
 372  *   FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
 373  *
 374  **/
 375 typedef int fna_vres_get_usage_t
 376    (const frsh_resource_id_t resource_id,
 377     const fna_vres_id_t vres,
 378     struct timespec *usage);
 379
 380 /**
 381  * fna_vres_get_remaining_budget()
 382  *
 383  * This function stores in the variable pointed to by budget the
 384  * remaining execution-time budget associated with the specified
 385  * vres in the present period.
 386  *
 387  * @param[in] resource_id The network we are referring to (a protocol
 388  * could be able to handle several networks at the same time)
 389  * @param[in] vres The internal virtual resource id
 390  * @param[out] remaining_budget  The remaining budget for this period
 391  *
 392  *  @return
 393  *   0 if there are no errors \n
 394  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 395  *   FNA_ERR_NOT_CONTRACTED_VRES: if the vres is not contracted \n
 396  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 397  *   FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
 398  *   FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
 399  *
 400  **/
 401 typedef int fna_vres_get_remaining_budget_t
 402    (const frsh_resource_id_t resource_id,
 403     const fna_vres_id_t vres,
 404     struct timespec *remaining_budget);
 405
 406 /**
 407  * fna_vres_get_budget_and_period()
 408  *
 409  * This function gets the budget and period associated with the specified vres
 410  * for each period. If one of these pointers is NULL, the corresponding
 411  * information is not stored.
 412  *
 413  * @param[in] resource_id The network we are referring to (a protocol
 414  * could be able to handle several networks at the same time)
 415  * @param[in] vres The internal virtual resource id
 416  * @param[out] budget The budget associated to vres
 417  * @param[out] period  The period associated to vres
 418  *
 419  * @return
 420  *   0 if there are no errors \n
 421  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 422  *   FNA_ERR_NOT_CONTRACTED_VRES: if the vres is not contracted \n
 423  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 424  *   FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
 425  *   FNA_ERR_BAD_ARGUMENT: if both pointers are NULL \n
 426  *
 427  **/
 428 typedef int fna_vres_get_budget_and_period_t
 429    (const frsh_resource_id_t resource_id,
 430     const fna_vres_id_t vres,
 431     struct timespec *budget,
 432     struct timespec *period);
 433
 434 /*@}*/
 435
 436 ///////////////////////////////////////////////////////////////////
 437 //           SPARE CAPACITY FUNCIONS
 438 ///////////////////////////////////////////////////////////////////
 439
 440 /**
 441  * @defgroup fnaspare FNA Spare Capacity
 442  * @ingroup fna
 443  *
 444  * The following functions are used to get spare capacity data
 445  *
 446  * @{
 447  **/
 448
 449 /**
 450  * fna_resource_get_capacity()
 451  *
 452  * This operation gets the spare capacity currently assigned to a importance
 453  * level. If we divide this value by UINT32_MAX we will get the network
 454  * utilization associated to the spare capacity of a importance level.
 455  *
 456  * The following is typically in stdint.h: \n
 457  *  - typedef unsigned int uint32_t;  \n
 458  *  - # define UINT32_MAX  (4294967295U)  \n
 459  *
 460  * @param[in] resource_id The network we are referring to (a protocol
 461  * could be able to handle several networks at the same time)
 462  * @param[in] importance The importance we want the capacity of
 463  * @param[out] capacity The spare capacity for that importance level
 464  *
 465  * @return
 466  *   0 if there are no errors \n
 467  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 468  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 469  *   FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
 470  *   FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
 471  *
 472  **/
 473 typedef int fna_resource_get_capacity_t
 474    (const frsh_resource_id_t resource_id,
 475     const int importance,
 476     uint32_t *capacity);
 477
 478 /**
 479  * fna_resource_get_total_weight()
 480  *
 481  * This function gets the sum of the weight parameters for all vres in a
 482  * network of an importance level.
 483  *
 484  * @param[in] resource_id The network we are referring to (a protocol
 485  * could be able to handle several networks at the same time)
 486  * @param[in] importance The importance we want the total weight of
 487  * @param[out] total_weight The total weight for that importance level
 488  *
 489  * @return
 490  *   0 if there are no errors \n
 491  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 492  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 493  *   FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
 494  *   FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
 495  *
 496  **/
 497 typedef int fna_resource_get_total_weight_t
 498    (const frsh_resource_id_t resource_id,
 499     const int importance,
 500     int *total_weight);
 501
 502 /**
 503  * fna_vres_decrease_capacity()
 504  *
 505  * This function allows to ask for less budget and period than what we
 506  * received. The request must be compatible with the rest of contract
 507  * parameters of the vres. If we want to recover the released capacity
 508  * we will need to renegotiate.
 509  *
 510  * @param[in] resource_id The network we are referring to (a protocol
 511  * could be able to handle several networks at the same time)
 512  * @param[in] vres The internal virtual resource id
 513  * @param[in] new_budget The new_budget
 514  * @param[in] new_period The new Period
 515  *
 516  * @return
 517  *   0 if there are no errors \n
 518  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 519  *   FNA_ERR_NOT_CONTRACTED_VRES: if the vres is not contracted \n
 520  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 521  *   FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
 522  *   FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
 523  *   FNA_ERR_CONTRACT_REJECTED: if it is incompatible with the current
 524  *      contract \n
 525  *
 526  **/
 527 typedef int fna_vres_decrease_capacity_t
 528    (const frsh_resource_id_t resource_id,
 529     const fna_vres_id_t vres,
 530     const struct timespec new_budget,
 531     const struct timespec new_period);
 532
 533 /*@}*/
 534
 535 ///////////////////////////////////////////////////////////////////
 536 //           SEND RECEIVE OPERATIONS
 537 ///////////////////////////////////////////////////////////////////
 538
 539 /**
 540  * @defgroup fnasendrecv FNA Send and Receive
 541  * @ingroup fna
 542  *
 543  * The following functions are used to send and receive
 544  *
 545  * @{
 546  **/
 547
 548 typedef enum {
 549     FRSH_SEND_ENDPOINT_TYPE,
 550     FRSH_RECEIVE_ENDPOINT_TYPE
 551 } frsh_endpoint_type_t;
 552
 553 typedef struct {
 554     frsh_endpoint_type_t endpoint_type; // send_endpoint or receive_endpoint
 555     fna_vres_id_t vres;                 // only for send_endpoints
 556     bool is_bound;                      // only for send_endpoints
 557     frsh_network_address_t destination; // only for send_endpoints
 558     frsh_resource_id_t resource_id;
 559     frsh_stream_id_t stream_id;
 560     frsh_protocol_info_t protocol_info;
 561     frsh_endpoint_queueing_info_t queue_info;
 562     union {
 563         frsh_send_endpoint_protocol_info_t send;
 564         frsh_receive_endpoint_protocol_info_t receive;
 565     } endpoint_protocol_info;
 566 } fna_endpoint_data_t;
 567
 568 /**
 569  * fna_send_sync()
 570  *
 571  * Similar to previous function but now the sending thread gets blocked
 572  * until the message is already sent to the network.
 573  *
 574  * @param[in] endpoint The send endpoint we are sending through. It must
 575  *    be bound to a virtual resource (resource_id is in the endpoint).
 576  * @param[in] msg The message we want to send
 577  * @param[in] size The size in bytes of the message
 578  *
 579  * @returns
 580  *   0 if there are no errors \n
 581  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 582  *   FNA_ERR_NOT_BOUND: if endpoint is not bound to a valid vres \n
 583  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 584  *   FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
 585  *   FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
 586  *   FNA_ERR_TOO_LARGE: if the message is too large for the network protocol \n
 587  *   FNA_ERR_BUFFER_FULL: if the message has been discarded because
 588  *   the queue is full (and does not have the policy FNA_QP_OLDEST) \n
 589  *
 590  **/
 591 typedef int fna_send_sync_t
 592    (const fna_endpoint_data_t *endpoint,
 593     const void *msg,
 594     const size_t size);
 595
 596 /**
 597  * fna_send_async()
 598  *
 599  * This operation sends a message stored in msg and of length size
 600  * through the given send endpoint. The operation is non-blocking and
 601  * returns immediately.
 602  *
 603  * @param[in] endpoint The send endpoint we are sending through. It must
 604  *    be bound to a virtual resource (resource_id is in the endpoint).
 605  * @param[in] msg The message we want to send
 606  * @param[in] size The size in bytes of the message
 607  *
 608  * @returns
 609  *   0 if there are no errors \n
 610  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 611  *   FNA_ERR_NOT_BOUND: if endpoint is not bound to a valid vres \n
 612  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 613  *   FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
 614  *   FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
 615  *   FNA_ERR_TOO_LARGE: if the message is too large for the network protocol \n
 616  *   FNA_ERR_BUFFER_FULL: if the message has been discarded because
 617  *   the queue is full (and does not have the policy FNA_QP_OLDEST) \n
 618  *
 619  **/
 620 typedef int fna_send_async_t
 621    (const fna_endpoint_data_t *endpoint,
 622     const void *msg,
 623     const size_t size);
 624
 625 /**
 626  * fna_receive_sync()
 627  *
 628  * This operation is used to receive messages from the network with a
 629  * blocking behavior (if there are no messages this operation blocks
 630  * the calling thread).
 631  *
 632  * When a message is available, it is copied to buffer (up to its size).
 633  * The number of bytes copied is returned in received_bytes. The rest
 634  * of the bytes of that message will be lost or not depending on the
 635  * protocol (FNA_ERR_NO_SPACE will be returned if it is).
 636  *
 637  * The function fails with FNA_ERR_NO_SPACE if the buffersize is
 638  * too small for the message received.  In this case the message is
 639  * lost.
 640  *
 641  * Messages arriving at a receiver buffer that is full will be handled
 642  * according to the queueing policy of the endpoint (overwrite oldest,
 643  * discard it,etc).
 644  *
 645  * @param[in] endpoint The receive endpoint we are receiving from.
 646  *    (resource_id is in the endpoint).
 647  * @param[out] buffer Buffer for storing the received message
 648  * @param[in] buffer_size The size in bytes of this buffer
 649  * @param[out] received_bytes The actual number of received bytes
 650  * @param[out] from Address of the sender node
 651  *
 652  * @return
 653  *   0 if there are no errors \n
 654  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 655  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 656  *   FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
 657  *   FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
 658  *   FNA_ERR_NO_SPACE: if the message size is bigger than the
 659  *      provided buffer. \n
 660  *
 661  **/
 662 typedef int fna_receive_sync_t
 663    (const fna_endpoint_data_t *endpoint,
 664     void *buffer,
 665     const size_t buffer_size,
 666     size_t *received_bytes,
 667     frsh_network_address_t *from);
 668
 669 /**
 670  * fna_receive_async()
 671  *
 672  * This operation is similar to the previous one but it works in a non
 673  * blocking (asynchronous) fashion.  If no message is available it
 674  * returns with error FNA_NO_MESSAGE.
 675  *
 676  * @param[in] endpoint The receive endpoint we are receiving from.
 677  *    (resource_id is in the endpoint).
 678  * @param[out] buffer Buffer for storing the received message
 679  * @param[in] buffer_size The size in bytes of this buffer
 680  * @param[out] received_bytes The actual number of received bytes
 681  * @param[out] from Address of the sender node
 682  *
 683  * @return
 684  *   0 if there are no errors \n
 685  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 686  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 687  *   FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
 688  *   FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
 689  *   FNA_ERR_NO_SPACE: if the message size is bigger than the
 690  *      provided buffer. \n
 691  *   FNA_NO_MESSAGE: if no messages are available in the queue. \n
 692  *
 693  **/
 694 typedef int fna_receive_async_t
 695    (const fna_endpoint_data_t *endpoint,
 696     void *buffer,
 697     const size_t buffer_size,
 698     size_t *received_bytes,
 699     frsh_network_address_t *from);
 700
 701 /**
 702  * fna_send_endpoint_get_status()
 703  *
 704  * This function tells the number of messages still pending in the
 705  * endpoint queue, whether the network is up or down with some
 706  * optional information which is protocol_dependent.
 707  *
 708  * @param[in] endpoint The send endpoint (resource_id is in the endpoint).
 709  * @param[out] number_of_pending_messages The number of pending messages
 710  * @param[out] network_status How is the network (up, down..)
 711  * @param[out] protocol_status Protocol dependent status info
 712  *
 713  * @return
 714  *   0 if there are no errors \n
 715  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 716  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 717  *   FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
 718  *   FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
 719  *
 720  **/
 721 typedef int fna_send_endpoint_get_status_t
 722    (const fna_endpoint_data_t *endpoint,
 723     int *number_of_pending_messages,
 724     frsh_endpoint_network_status_t *network_status,
 725     frsh_protocol_status_t *protocol_status);
 726
 727 /**
 728  * fna_receive_endpoint_create_callback()
 729  *
 730  * This operation is a called from frsh_receive_endpoint_create with a
 731  * receive_endpoint structure already filled.
 732  *
 733  * Receiving endpoints are not bound to any network vres, this is
 734  * because don't originate any traffic.
 735  *
 736  * @param[in] endpoint the endpoint object.
 737  *
 738  * @return
 739  *   0 if there are no errors \n
 740  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 741  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 742  *   FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
 743  *   FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
 744  **/
 745 typedef int fna_receive_endpoint_create_callback_t
 746    (fna_endpoint_data_t *endpoint);
 747
 748 /**
 749  * fna_receive_endpoint_get_pending_messages
 750  *
 751  * This function tells the number of messages still pending in the
 752  * endpoint queue, whether the network is up or down and some optional
 753  * information which is protocol dependent.
 754  *
 755  * @param[in] endpoint The receive endpoint (resource_id is in the endpoint).
 756  * @param[out] number_of_pending_messages The number of pending messages
 757  * @param[out] network_status How is the network (up, down..)
 758  * @param[out] protocol_status Protocol dependent status info
 759  *
 760  * @return
 761  *   0 if there are no errors \n
 762  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 763  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 764  *   FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
 765  *   FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
 766  *
 767  **/
 768 typedef int fna_receive_endpoint_get_status_t
 769    (const fna_endpoint_data_t *endpoint,
 770     int *number_of_pending_messages,
 771     frsh_endpoint_network_status_t *network_status,
 772     frsh_protocol_status_t *protocol_status);
 773
 774 /*@}*/
 775
 776 //////////////////////////////////////////////////////////////////////
 777 //           NETWORK CONFIGURATION FUNCTIONS
 778 //////////////////////////////////////////////////////////////////////
 779
 780 /**
 781  * @defgroup frshfnaconfig FNA Network Configuration
 782  * @ingroup fna
 783  *
 784  * These functions are needed to set/get some network dependent values
 785  *
 786  * @{
 787  **/
 788
 789 /**
 790  * fna_network_get_max_message_size()
 791  *
 792  * This operation gives the maximum number of bytes that can be sent
 793  * at a time through the send function when using the network designated by
 794  * 'resource_id' and sending it to 'destination'.
 795  *
 796  * If the application needs to send bigger messages it will have to
 797  * split them.
 798  *
 799  * Some protocols, like IP, are capable of sending large messages
 800  * (and use fragmentation internally) but other protocols don't.
 801  *
 802  * @param[in] resource_id The network we want the tx time from.
 803  * @param[in] destination The destination address
 804  * @param[out] max_size The maximum number of bytes for each message
 805  *
 806  * @return
 807  *   0 if there are no errors \n
 808  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 809  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 810  *   FNA_ERR_RESOURCE_ID_INVALID: if resource id does not represent
 811  *   a network accessible from the current processing node \n
 812  *   FNA_ERR_BAD_ARGUMENT: if pointers are NULL or destination is
 813  *   invalid \n
 814  *
 815  **/
 816 typedef int fna_network_get_max_message_size_t
 817    (const frsh_resource_id_t resource_id,
 818     const frsh_network_address_t destination,
 819     size_t *max_size);
 820
 821 /**
 822  * fna_network_bytes_to_budget()
 823  *
 824  * This operation converts a number of bytes into a temporal budget for
 825  * a specific network. Network overheads are not included here but are
 826  * considered internally when negotiating a specific contract.
 827  *
 828  * @param[in] resource_id The network
 829  * @param[in] nbytes Number of bytes
 830  * @param[out] budget The network budget for nbytes
 831  *
 832  * @return
 833  *   0 if there are no errors \n
 834  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 835  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 836  *   FNA_ERR_RESOURCE_ID_INVALID: if resource id does not represent
 837  *   a network accessible from the current processing node \n
 838  *   FNA_ERR_BAD_ARGUMENT: if pointers are NULL or nbytes is less
 839  *   than zero \n
 840  *
 841  **/
 842 typedef int fna_network_bytes_to_budget_t
 843    (const frsh_resource_id_t resource_id,
 844     const size_t nbytes,
 845     frsh_rel_time_t *budget);
 846
 847 /**
 848  * fna_network_budget_to_bytes()
 849  *
 850  * This operation converts a temporal budget into a number of bytes for
 851  * a specific network. Network overheads are not included.
 852  *
 853  * @param[in] resource_id The network
 854  * @param[in] budget The network budget for nbytes
 855  * @param[out] nbytes Number of bytes
 856  *
 857  * @return
 858  *   0 if there are no errors \n
 859  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 860  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 861  *   FNA_ERR_RESOURCE_ID_INVALID: if resource id does not represent
 862  *   a network accessible from the current processing node \n
 863  *   FNA_ERR_BAD_ARGUMENT: if pointers are NULL or budget refers to
 864  *   an invalid time value \n
 865  *
 866  **/
 867 typedef int fna_network_budget_to_bytes_t
 868    (const frsh_resource_id_t resource_id,
 869     const frsh_rel_time_t *budget,
 870     size_t *nbytes);
 871
 872 /**
 873  * fna_network_get_min_effective_budget()
 874  *
 875  * This operation gets the minimum effective budget for a network. Each message
 876  * consumes a contracted budget in "chunks" (i.e: packets) that we call
 877  * minimum effective budget.
 878  *
 879  * A negotiated contract, for N bytes in a period T, means that there is a
 880  * virtual resource that reserves for the user:
 881  *
 882  *   Ceiling ((N bytes) / budget_to_bytes (min_effective_budget)) "CHUNKS"
 883  *
 884  * Note that if the user decides not to send these N bytes at once but, say,
 885  * one byte at a time, it will consume one "CHUNK" at a time and the reserved
 886  * budget will become exhausted before sending all the bytes.
 887  *
 888  * @param[in] resource_id The network
 889  * @param[out] budget The network budget
 890  *
 891  * @return
 892  *   0 if there are no errors \n
 893  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 894  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 895  *   FNA_ERR_RESOURCE_ID_INVALID: if resource id does not represent
 896  *   a network accessible from the current processing node \n
 897  *   FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
 898  *
 899  **/
 900 typedef int fna_network_get_min_effective_budget_t
 901    (const frsh_resource_id_t resource_id,
 902     frsh_rel_time_t *budget);
 903
 904 /*@}*/
 905
 906 typedef struct {
 907     fna_init_t *fna_init;
 908     fna_contract_negotiate_t *fna_contract_negotiate;
 909     fna_contract_renegotiate_sync_t *fna_contract_renegotiate_sync;
 910     fna_contract_renegotiate_async_t *fna_contract_renegotiate_async;
 911     fna_vres_get_renegotiation_status_t *fna_vres_get_renegotiation_status;
 912     fna_vres_destroy_t *fna_vres_destroy;
 913     fna_vres_get_contract_t *fna_vres_get_contract;
 914     fna_vres_get_usage_t *fna_vres_get_usage;
 915     fna_vres_get_remaining_budget_t *fna_vres_get_remaining_budget;
 916     fna_vres_get_budget_and_period_t *fna_vres_get_budget_and_period;
 917     fna_resource_get_capacity_t *fna_resource_get_capacity;
 918     fna_resource_get_total_weight_t *fna_resource_get_total_weight;
 919     fna_vres_decrease_capacity_t *fna_vres_decrease_capacity;
 920     fna_send_sync_t *fna_send_sync;
 921     fna_send_async_t *fna_send_async;
 922     fna_receive_sync_t *fna_receive_sync;
 923     fna_receive_async_t *fna_receive_async;
 924     fna_send_endpoint_get_status_t *fna_send_endpoint_get_status;
 925     fna_receive_endpoint_create_callback_t *fna_receive_endpoint_created;
 926     fna_receive_endpoint_get_status_t *fna_receive_endpoint_get_status;
 927     fna_network_get_max_message_size_t *fna_network_get_max_message_size;
 928     fna_network_bytes_to_budget_t *fna_network_bytes_to_budget;
 929     fna_network_budget_to_bytes_t *fna_network_budget_to_bytes;
 930     fna_network_get_min_effective_budget_t *fna_network_get_min_eff_budget;
 931 } fna_operations_t;
 932
 933 #endif // _FNA_H_
 934