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