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, etc */
  70 #include "frsh_core_types.h"
  71 /* for frsh_network_address_t, frsh_stream_id_t */
  72 #include "frsh_distributed_types.h"
  73 /* for timespec */
  74 #include <time.h>
  75 /* for ERROR constants */
  76 // #include "fna_error.h"
  77 /* for uint32_t, UINT32_MAX */
  78 #include <stdint.h>
  79
  80 /**
  81  * @defgroup fna FNA Private Interface
  82  *
  83  * FNA is a Network adaption layer that allows to plugin new
  84  * network protocols to the distributed module.
  85  *
  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.
  89  *
  90  **/
  91
  92
  93 //////////////////////////////////////////////////////////////////////
  94 //           INITIALIZATION
  95 //////////////////////////////////////////////////////////////////////
  96
  97 /**
  98  * @defgroup fnainit FNA Initialization
  99  * @ingroup fna
 100  *
 101  * These functions need to be called before using any network
 102  *
 103  * @{
 104  **/
 105
 106 /**
 107  * fna_init()
 108  *
 109  * This function will be hooked to the frsh_init function and it is
 110  * intented to initialize the protocol and its structures.
 111  *
 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)
 114  *
 115  * @return
 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
 121  *
 122  **/
 123 typedef int fna_init_t(const frsh_resource_id_t resource_id);
 124
 125 /*@}*/
 126
 127 ///////////////////////////////////////////////////////////////////
 128 //           VIRTUAL RESOURCES
 129 ///////////////////////////////////////////////////////////////////
 130
 131 /**
 132  * @defgroup fnavres FNA Virtual Resources
 133  * @ingroup fna
 134  *
 135  * The following functions are used to negotiate, renegotiate and cancel
 136  * virtual network resources.
 137  *
 138  * @{
 139  **/
 140
 141 /**
 142  * fna_vres_id_t
 143  *
 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)
 147  *
 148  **/
 149 typedef uint16_t fna_vres_id_t;
 150
 151 /**
 152  * fna_contract_negotiate()
 153  *
 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.
 157  *
 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.
 163  *
 164  * This is a potentially blocking operation, it returns when the
 165  * system has either rejected the contract, or admitted it and made it
 166  * effective.
 167  *
 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
 172  *
 173  * @return
 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
 182  *
 183  **/
 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);
 188
 189 /**
 190  * fna_contract_renegotiate_sync()
 191  *
 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
 201  * effective.
 202  *
 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
 207  *
 208  *  @return
 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
 217  *
 218  **/
 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);
 223
 224 /**
 225  * fna_contract_renegotiate_async()
 226  *
 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.
 237  *
 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.
 244  *
 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.
 253  *
 254  * @return
 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
 263  *
 264  **/
 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);
 271
 272 /**
 273  * fna_vres_get_renegotiation_status()
 274  *
 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
 278  * requested.
 279  *
 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
 283  *
 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)
 290  *
 291  * @return
 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
 298  *
 299  **/
 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);
 304
 305 /**
 306  * fna_vres_destroy()
 307  *
 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.
 312  *
 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
 316  *
 317  * @return
 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
 324  *
 325  **/
 326 typedef int fna_vres_destroy_t
 327    (const frsh_resource_id_t resource_id,
 328     const fna_vres_id_t vres);
 329
 330 /**
 331  * fna_vres_get_contract()
 332  *
 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.
 336  *
 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
 341  *
 342  * @return
 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
 349  *
 350  **/
 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);
 355
 356 /**
 357  * fna_vres_get_usage()
 358  *
 359  * This function gets the execution time spent by all messages that have been
 360  * sent through the specified vres.
 361  *
 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
 366  *
 367  * @return
 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
 374  *
 375  **/
 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);
 380
 381 /**
 382  * fna_vres_get_remaining_budget()
 383  *
 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.
 387  *
 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
 392  *
 393  *  @return
 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
 400  *
 401  **/
 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);
 406
 407 /**
 408  * fna_vres_get_budget_and_period()
 409  *
 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.
 413  *
 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
 419  *
 420  * @return
 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
 427  *
 428  **/
 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);
 434
 435 /*@}*/
 436
 437 ///////////////////////////////////////////////////////////////////
 438 //           SPARE CAPACITY FUNCIONS
 439 ///////////////////////////////////////////////////////////////////
 440
 441 /**
 442  * @defgroup fnaspare FNA Spare Capacity
 443  * @ingroup fna
 444  *
 445  * The following functions are used to get spare capacity data
 446  *
 447  * @{
 448  **/
 449
 450 /**
 451  * fna_resource_get_capacity()
 452  *
 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.
 456  *
 457  * The following is typically in stdint.h: \n
 458  *  - typedef unsigned int uint32_t;  \n
 459  *  - # define UINT32_MAX  (4294967295U)  \n
 460  *
 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
 465  *
 466  * @return
 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
 472  *
 473  **/
 474 typedef int fna_resource_get_capacity_t
 475    (const frsh_resource_id_t resource_id,
 476     const int importance,
 477     uint32_t *capacity);
 478
 479 /**
 480  * fna_resource_get_total_weight()
 481  *
 482  * This function gets the sum of the weight parameters for all vres in a
 483  * network of an importance level.
 484  *
 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
 489  *
 490  * @return
 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
 496  *
 497  **/
 498 typedef int fna_resource_get_total_weight_t
 499    (const frsh_resource_id_t resource_id,
 500     const int importance,
 501     int *total_weight);
 502
 503 /**
 504  * fna_vres_decrease_capacity()
 505  *
 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.
 510  *
 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
 516  *
 517  * @return
 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
 525  *      contract \n
 526  *
 527  **/
 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);
 533
 534 /*@}*/
 535
 536 ///////////////////////////////////////////////////////////////////
 537 //           SEND RECEIVE OPERATIONS
 538 ///////////////////////////////////////////////////////////////////
 539
 540 /**
 541  * @defgroup fnasendrecv FNA Send and Receive
 542  * @ingroup fna
 543  *
 544  * The following functions are used to send and receive
 545  *
 546  * @{
 547  **/
 548
 549 typedef enum {
 550     FRSH_SEND_ENDPOINT_TYPE,
 551     FRSH_RECEIVE_ENDPOINT_TYPE
 552 } frsh_endpoint_type_t;
 553
 554 typedef struct {
 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;
 563     union {
 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;
 568
 569 /**
 570  * fna_send_sync()
 571  *
 572  * Similar to previous function but now the sending thread gets blocked
 573  * until the message is already sent to the network.
 574  *
 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
 579  *
 580  * @returns
 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
 590  *
 591  **/
 592 typedef int fna_send_sync_t
 593    (const fna_endpoint_data_t *endpoint,
 594     const void *msg,
 595     const size_t size);
 596
 597 /**
 598  * fna_send_async()
 599  *
 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.
 603  *
 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
 608  *
 609  * @returns
 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
 619  *
 620  **/
 621 typedef int fna_send_async_t
 622    (const fna_endpoint_data_t *endpoint,
 623     const void *msg,
 624     const size_t size);
 625
 626 /**
 627  * fna_receive_sync()
 628  *
 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).
 632  *
 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).
 637  *
 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
 640  * lost.
 641  *
 642  * Messages arriving at a receiver buffer that is full will be handled
 643  * according to the queueing policy of the endpoint (overwrite oldest,
 644  * discard it,etc).
 645  *
 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
 652  *
 653  * @return
 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
 661  *
 662  **/
 663 typedef int fna_receive_sync_t
 664    (const fna_endpoint_data_t *endpoint,
 665     void *buffer,
 666     const size_t buffer_size,
 667     size_t *received_bytes,
 668     frsh_network_address_t *from);
 669
 670 /**
 671  * fna_receive_async()
 672  *
 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.
 676  *
 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
 683  *
 684  * @return
 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
 693  *
 694  **/
 695 typedef int fna_receive_async_t
 696    (const fna_endpoint_data_t *endpoint,
 697     void *buffer,
 698     const size_t buffer_size,
 699     size_t *received_bytes,
 700     frsh_network_address_t *from);
 701
 702 /**
 703  * fna_send_endpoint_get_status()
 704  *
 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.
 708  *
 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
 713  *
 714  * @return
 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
 720  *
 721  **/
 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);
 727
 728 /**
 729  * fna_receive_endpoint_create_callback()
 730  *
 731  * This operation is a called from frsh_receive_endpoint_create with a
 732  * receive_endpoint structure already filled.
 733  *
 734  * Receiving endpoints are not bound to any network vres, this is
 735  * because don't originate any traffic.
 736  *
 737  * @param[in] endpoint the endpoint object.
 738  *
 739  * @return
 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
 745  **/
 746 typedef int fna_receive_endpoint_create_callback_t
 747    (const fna_endpoint_data_t *endpoint);
 748
 749 /**
 750  * fna_receive_endpoint_get_pending_messages
 751  *
 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.
 755  *
 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
 760  *
 761  * @return
 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
 767  *
 768  **/
 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);
 774
 775 /*@}*/
 776
 777 //////////////////////////////////////////////////////////////////////
 778 //           NETWORK CONFIGURATION FUNCTIONS
 779 //////////////////////////////////////////////////////////////////////
 780
 781 /**
 782  * @defgroup frshfnaconfig FNA Network Configuration
 783  * @ingroup fna
 784  *
 785  * These functions are needed to set/get some network dependent values
 786  *
 787  * @{
 788  **/
 789
 790 /**
 791  * fna_network_get_max_message_size()
 792  *
 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'.
 796  *
 797  * If the application needs to send bigger messages it will have to
 798  * split them.
 799  *
 800  * Some protocols, like IP, are capable of sending large messages
 801  * (and use fragmentation internally) but other protocols don't.
 802  *
 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
 806  *
 807  * @return
 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
 814  *   invalid \n
 815  *
 816  **/
 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,
 820     size_t *max_size);
 821
 822 /**
 823  * fna_network_bytes_to_budget()
 824  *
 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.
 828  *
 829  * @param[in] resource_id The network
 830  * @param[in] nbytes Number of bytes
 831  * @param[out] budget The network budget for nbytes
 832  *
 833  * @return
 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
 840  *   than zero \n
 841  *
 842  **/
 843 typedef int fna_network_bytes_to_budget_t
 844    (const frsh_resource_id_t resource_id,
 845     const size_t nbytes,
 846     struct timespec *budget);
 847
 848 /**
 849  * fna_network_budget_to_bytes()
 850  *
 851  * This operation converts a temporal budget into a number of bytes for
 852  * a specific network. Network overheads are not included.
 853  *
 854  * @param[in] resource_id The network
 855  * @param[in] budget The network budget for nbytes
 856  * @param[out] nbytes Number of bytes
 857  *
 858  * @return
 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
 866  *
 867  **/
 868 typedef int fna_network_budget_to_bytes_t
 869    (const frsh_resource_id_t resource_id,
 870     const struct timespec *budget,
 871     size_t *nbytes);
 872
 873 /**
 874  * fna_network_get_min_effective_budget()
 875  *
 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.
 879  *
 880  * A negotiated contract, for N bytes in a period T, means that there is a
 881  * virtual resource that reserves for the user:
 882  *
 883  *   Ceiling ((N bytes) / budget_to_bytes (min_effective_budget)) "CHUNKS"
 884  *
 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.
 888  *
 889  * @param[in] resource_id The network
 890  * @param[out] budget The network budget
 891  *
 892  * @return
 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
 899  *
 900  **/
 901 typedef int fna_network_get_min_effective_budget_t
 902    (const frsh_resource_id_t resource_id,
 903     struct timespec *budget);
 904
 905 /*@}*/
 906
 907 typedef struct {
 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;
 932 } fna_operations_t;
 933
 934 #endif // _FNA_H_
 935