include/fna.h

   1 // -----------------------------------------------------------------------
   2 //  Copyright (C) 2006 - 2007 FRESCOR consortium partners:
   3 //
   4 //    Universidad de Cantabria,              SPAIN
   5 //    University of York,                    UK
   6 //    Scuola Superiore Sant'Anna,            ITALY
   7 //    Kaiserslautern University,             GERMANY
   8 //    Univ. Politécnica  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 for a link to partners' websites
  17 //
  18 //           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 //   FSF API web pages: http://marte.unican.es/fsf/docs
  32 //                      http://shark.sssup.it/contrib/first/docs/
  33 //
  34 //  This file is part of FRSH API
  35 //
  36 //  FRSH API is free software; you can  redistribute it and/or  modify
  37 //  it under the terms of  the GNU General Public License as published by
  38 //  the Free Software Foundation;  either  version 2, or (at  your option)
  39 //  any later version.
  40 //
  41 //  FRSH API  is distributed  in  the hope  that  it  will  be useful,  but
  42 //  WITHOUT  ANY  WARRANTY;     without  even the   implied   warranty  of
  43 //  MERCHANTABILITY  or  FITNESS FOR  A  PARTICULAR PURPOSE. See  the  GNU
  44 //  General Public License for more details.
  45 //
  46 //  You should have  received a  copy of  the  GNU  General Public License
  47 //  distributed  with  FRSH API;  see file COPYING.   If not,  write to the
  48 //  Free Software  Foundation,  59 Temple Place  -  Suite 330,  Boston, MA
  49 //  02111-1307, USA.
  50 //
  51 //  As a special exception, if you include this header file into source
  52 //  files to be compiled, this header file does not by itself cause
  53 //  the resulting executable to be covered by the GNU General Public
  54 //  License.  This exception does not however invalidate any other
  55 //  reasons why the executable file might be covered by the GNU General
  56 //  Public License.
  57 // -----------------------------------------------------------------------
  58
  59 //==============================================
  60 //  ******** ****     **     **
  61 //  **///// /**/**   /**    ****
  62 //  **      /**//**  /**   **//**
  63 //  ******* /** //** /**  **  //**
  64 //  **////  /**  //**/** **********
  65 //  **      /**   //****/**//////**
  66 //  **      /**    //***/**     /**
  67 //  /       //      /// //      //
  68 //
  69 // FNA(Frescor Network Adaptation layer), pronounced "efe ene a"
  70 //==============================================================
  71
  72 #ifndef _FNA_H_
  73 #define _FNA_H_
  74
  75 #include "frsh_core_types.h" /* for frsh_resource_id_t, frsh_contract_t, etc */
  76 #include "fna_error.h" /* for ERROR constants */
  77 #include <stdint.h> /* for uint32_t, UINT32_MAX */
  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 //           INITIALIZATION
  93 //////////////////////////////////////////////////////////////////////
  94
  95 /**
  96  * @defgroup fnainit FNA Initialization
  97  * @ingroup fna
  98  *
  99  * These functions need to be called before using any network
 100  *
 101  * @{
 102  **/
 103
 104 /**
 105  * fna_init()
 106  *
 107  * This function will be hooked to the frsh_init function and it is
 108  * intented to initialize the protocol and its structures.
 109  *
 110  * @param[in]  resource_id The network we are referring to (a protocol
 111  * could be able to handle several networks at the same time)
 112  *
 113  * @return
 114  *   FNA_NO_ERROR \n
 115  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 116  *   FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
 117  *   FNA_ERR_ALREADY_INITIALIZED:
 118  *      if the function has already been called before (with success) \n
 119  *
 120  **/
 121 int fna_init(const frsh_resource_id_t resource_id);
 122
 123 /*@}*/
 124
 125 ///////////////////////////////////////////////////////////////////
 126 //           VIRTUAL RESOURCES
 127 ///////////////////////////////////////////////////////////////////
 128
 129 /**
 130  * @defgroup fnavres FNA Virtual Resources
 131  * @ingroup fna
 132  *
 133  * The following functions are used to negotiate, renegotiate and cancel
 134  * virtual network resources.
 135  *
 136  * @{
 137  **/
 138
 139 /**
 140  * fna_vres_id_t
 141  *
 142  * Internal virtual resource id. The type fna_vres_id_t is a pointer to void.
 143  * The FRSH layer will keep a map between the frsh_vres_id_t, this
 144  * pointer and the resource_id. This pointer could be used as the ID
 145  * itself using casting, or as internal pointer to any structure.
 146  *
 147  **/
 148 typedef void *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  *   FNA_NO_ERROR: 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 int fna_contract_negotiate
 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  *   FNA_NO_ERROR: 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 int fna_contract_renegotiate_sync
 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  *   FNA_NO_ERROR: in this case it also means contract accepted \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 int fna_contract_renegotiate_async
 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  *   FNA_NO_ERROR: in this case it also means contract accepted \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 int fna_vres_get_renegotiation_status
 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  *   FNA_NO_ERROR: in this case it also means contract accepted \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 int fna_vres_destroy
 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  *   FNA_NO_ERROR: in this case it also means contract accepted \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 int fna_vres_get_contract
 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  *   FNA_NO_ERROR: in this case it also means contract accepted \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 int fna_vres_get_usage
 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  *   FNA_NO_ERROR: in this case it also means contract accepted \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 int fna_vres_get_remaining_budget
 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  *   FNA_NO_ERROR: in this case it also means contract accepted \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 int fna_vres_get_budget_and_period
 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  *   FNA_NO_ERROR: in this case it also means contract accepted \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 int fna_resource_get_capacity
 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  *   FNA_NO_ERROR: in this case it also means contract accepted \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 int fna_resource_get_total_weight
 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  *   FNA_NO_ERROR: in this case it also means contract accepted \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 int fna_vres_decrease_capacity
 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 /**
 549  * fna_send_sync()
 550  *
 551  * Similar to previous function but now the sending thread gets blocked
 552  * until the message is already sent to the network.
 553  *
 554  * @param[in] endpoint The send endpoint we are sending through. It must
 555  *    be bound to a virtual resource (resource_id is in the endpoint).
 556  * @param[in] msg The message we want to send
 557  * @param[in] size The size in bytes of the message
 558  *
 559  * @returns
 560  *   FNA_NO_ERROR: in this case it also means contract accepted \n
 561  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 562  *   FNA_ERR_NOT_BOUND: if endpoint is not bound to a valid vres \n
 563  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 564  *   FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
 565  *   FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
 566  *   FNA_ERR_TOO_LARGE: if the message is too large for the network protocol \n
 567  *   FNA_ERR_BUFFER_FULL: if the message has been discarded because
 568  *   the queue is full (and does not have the policy FNA_QP_OLDEST) \n
 569  *
 570  **/
 571 int fna_send_sync
 572    (const frsh_send_endpoint_t *endpoint,
 573     const void *msg,
 574     const size_t size);
 575
 576 /**
 577  * fna_send_async()
 578  *
 579  * This operation sends a message stored in msg and of length size
 580  * through the given send endpoint. The operation is non-blocking and
 581  * returns immediately.
 582  *
 583  * @param[in] endpoint The send endpoint we are sending through. It must
 584  *    be bound to a virtual resource (resource_id is in the endpoint).
 585  * @param[in] msg The message we want to send
 586  * @param[in] size The size in bytes of the message
 587  *
 588  * @returns
 589  *   FNA_NO_ERROR: in this case it also means contract accepted \n
 590  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 591  *   FNA_ERR_NOT_BOUND: if endpoint is not bound to a valid vres \n
 592  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 593  *   FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
 594  *   FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
 595  *   FNA_ERR_TOO_LARGE: if the message is too large for the network protocol \n
 596  *   FNA_ERR_BUFFER_FULL: if the message has been discarded because
 597  *   the queue is full (and does not have the policy FNA_QP_OLDEST) \n
 598  *
 599  **/
 600 int fna_send_async
 601    (const frsh_send_endpoint_t *endpoint,
 602     const void *msg,
 603     const size_t size);
 604
 605 /**
 606  * fna_receive_sync()
 607  *
 608  * This operation is used to receive messages from the network with a
 609  * blocking behavior (if there are no messages this operation blocks
 610  * the calling thread).
 611  *
 612  * When a message is available, it is copied to buffer (up to its size).
 613  * The number of bytes copied is returned in received_bytes. The rest
 614  * of the bytes of that message will be lost or not depending on the
 615  * protocol (FNA_ERR_NO_SPACE will be returned if it is).
 616  *
 617  * The function fails with FNA_ERR_NO_SPACE if the buffersize is
 618  * too small for the message received.  In this case the message is
 619  * lost.
 620  *
 621  * Messages arriving at a receiver buffer that is full will be handled
 622  * according to the queueing policy of the endpoint (overwrite oldest,
 623  * discard it,etc).
 624  *
 625  * @param[in] endpoint The receive endpoint we are receiving from.
 626  *    (resource_id is in the endpoint).
 627  * @param[out] buffer Buffer for storing the received message
 628  * @param[in] buffer_size The size in bytes of this buffer
 629  * @param[out] received_bytes The actual number of received bytes
 630  *
 631  * @return
 632  *   FNA_NO_ERROR: in this case it also means contract accepted \n
 633  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 634  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 635  *   FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
 636  *   FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
 637  *   FNA_ERR_NO_SPACE: if the message size is bigger than the
 638  *      provided buffer. \n
 639  *
 640  **/
 641 int fna_receive_sync
 642    (const frsh_receive_endpoint_t *endpoint,
 643     void *buffer,
 644     const size_t buffer_size,
 645     size_t *received_bytes);
 646
 647 /**
 648  * fna_receive_async()
 649  *
 650  * This operation is similar to the previous one but it works in a non
 651  * blocking (asynchronous) fashion.  If no message is available it
 652  * returns with error FNA_NO_MESSAGE.
 653  *
 654  * @param[in] endpoint The receive endpoint we are receiving from.
 655  *    (resource_id is in the endpoint).
 656  * @param[out] buffer Buffer for storing the received message
 657  * @param[in] buffer_size The size in bytes of this buffer
 658  * @param[out] received_bytes The actual number of received bytes
 659  *
 660  * @return
 661  *   FNA_NO_ERROR: in this case it also means contract accepted \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  *   FNA_NO_MESSAGE: if no messages are available in the queue. \n
 669  *
 670  **/
 671 int fna_receive_async
 672    (const frsh_receive_endpoint_t *endpoint,
 673     void *buffer,
 674     const size_t buffer_size,
 675     size_t *received_bytes);
 676
 677 /**
 678  * fna_send_endpoint_get_status()
 679  *
 680  * This function tells the number of messages still pending in the
 681  * endpoint queue, whether the network is up or down with some
 682  * optional information which is protocol_dependent.
 683  *
 684  * @param[in] endpoint The send endpoint (resource_id is in the endpoint).
 685  * @param[out] number_of_pending_messages The number of pending messages
 686  * @param[out] network_status How is the network (up, down..)
 687  * @param[out] protocol_status Protocol dependent status info
 688  *
 689  * @return
 690  *   FNA_NO_ERROR: in this case it also means contract accepted \n
 691  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 692  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 693  *   FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
 694  *   FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
 695  *
 696  **/
 697 int fna_send_endpoint_get_status
 698    (const frsh_send_endpoint_t *endpoint,
 699     int *number_of_pending_messages,
 700     frsh_endpoint_network_status *network_status,
 701     frsh_protocol_status_t *protocol_status);
 702
 703 /**
 704  * fna_receive_endpoint_create()
 705  *
 706  * This operation creates a receive endpoint associated with a
 707  * undirectional stream within a network interface of the node.
 708  *
 709  * Receiving endpoints are not bound to any network vres, this is
 710  * because don't originate any traffic.
 711  *
 712  * Note that the protocol address is not needed for reception because
 713  * it can be determined internally by FRSH based on the network_id.
 714  *
 715  * Note also that messages may come from diferent originators.
 716  *
 717  * @param[in] resource_id  Id of the network from which we listen.
 718  * @param[in] stream_id  Id of the stream within the network.
 719  * @param[in] queueing_info Buffering information(queue size and
 720  *                          policy).
 721  * @param[in] protocol_info Extra protocol info opaque for the
 722  *                          application.
 723  * @param[out] endpoint  Placeholder for the endpoint object.
 724  *
 725  * @return
 726  *   FNA_NO_ERROR: in this case it also means contract accepted \n
 727  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 728  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 729  *   FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
 730  *   FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
 731  **/
 732 int fna_receive_endpoint_create
 733    (const frsh_resource_id_t resource_id,
 734     const frsh_stream_id_t stream_id,
 735     const frsh_endpoint_queueing_info_t queueing_info,
 736     const frsh_protocol_info_t protocol_info,
 737     frsh_receive_endpoint_t *endpoint);
 738
 739 /**
 740  * fna_receive_endpoint_get_pending_messages
 741  *
 742  * This function tells the number of messages still pending in the
 743  * endpoint queue, whether the network is up or down and some optional
 744  * information which is protocol dependent.
 745  *
 746  * @param[in] endpoint The receive endpoint (resource_id is in the endpoint).
 747  * @param[out] number_of_pending_messages The number of pending messages
 748  * @param[out] network_status How is the network (up, down..)
 749  * @param[out] protocol_status Protocol dependent status info
 750  *
 751  * @return
 752  *   FNA_NO_ERROR: in this case it also means contract accepted \n
 753  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 754  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 755  *   FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
 756  *   FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
 757  *
 758  **/
 759 int fna_receive_endpoint_get_status
 760    (const frsh_receive_endpoint_t *endpoint,
 761     int *number_of_pending_messages,
 762     frsh_endpoint_network_status *network_status,
 763     frsh_protocol_status_t *protocol_status);
 764
 765 /*@}*/
 766
 767 //////////////////////////////////////////////////////////////////////
 768 //           NETWORK CONFIGURATION FUNCTIONS
 769 //////////////////////////////////////////////////////////////////////
 770
 771 /**
 772  * @defgroup frshfnaconfig FNA Network Configuration
 773  * @ingroup fna
 774  *
 775  * These functions are needed to set/get some network dependent values
 776  *
 777  * @{
 778  **/
 779
 780 /**
 781  * fna_network_message_get_max_size()
 782  *
 783  * This operation gives the maximum number of bytes that can be sent
 784  * at a time through the send function when using the network designated by
 785  * 'resource_id' and sending it to 'destination'.
 786  *
 787  * If the application needs to send bigger messages it will have to
 788  * split them.
 789  *
 790  * Some protocols, like IP, are capable of sending large messages
 791  * (and use fragmentation internally) but other protocols don't.
 792  *
 793  * @param[in] resource_id The network we want the tx time from.
 794  * @param[in] destination The destination address
 795  * @param[out] max_size The maximum number of bytes for each message
 796  *
 797  * @return
 798  *   FNA_NO_ERROR \n
 799  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 800  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 801  *   FNA_ERR_RESOURCE_ID_INVALID: if resource id does not represent
 802  *   a network accessible from the current processing node \n
 803  *   FNA_ERR_BAD_ARGUMENT: if pointers are NULL or destination is
 804  *   invalid \n
 805  *
 806  **/
 807 int fna_network_message_get_max_size
 808    (const frsh_resource_id_t resource_id,
 809     const frsh_network_address_t destination,
 810     size_t *max_size);
 811
 812 /**
 813  * fna_network_bytes_to_budget()
 814  *
 815  * This operation converts a number of bytes into a temporal budget for
 816  * a specific network. Network overheads are not included here but are
 817  * considered internally when negotiating a specific contract.
 818  *
 819  * @param[in] resource_id The network
 820  * @param[in] nbytes Number of bytes
 821  * @param[out] budget The network budget for nbytes
 822  *
 823  * @return
 824  *   FNA_NO_ERROR \n
 825  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 826  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 827  *   FNA_ERR_RESOURCE_ID_INVALID: if resource id does not represent
 828  *   a network accessible from the current processing node \n
 829  *   FNA_ERR_BAD_ARGUMENT: if pointers are NULL or nbytes is less
 830  *   than zero \n
 831  *
 832  **/
 833 int fna_network_bytes_to_budget
 834    (const frsh_resource_id_t resource_id,
 835     const size_t nbytes,
 836     struct timespec *budget);
 837
 838 /**
 839  * fna_network_budget_to_bytes()
 840  *
 841  * This operation converts a temporal budget into a number of bytes for
 842  * a specific network. Network overheads are not included.
 843  *
 844  * @param[in] resource_id The network
 845  * @param[in] budget The network budget for nbytes
 846  * @param[out] nbytes Number of bytes
 847  *
 848  * @return
 849  *   FNA_NO_ERROR \n
 850  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 851  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 852  *   FNA_ERR_RESOURCE_ID_INVALID: if resource id does not represent
 853  *   a network accessible from the current processing node \n
 854  *   FNA_ERR_BAD_ARGUMENT: if pointers are NULL or budget refers to
 855  *   an invalid time value \n
 856  *
 857  **/
 858 int fna_network_budget_to_bytes
 859    (const frsh_resource_id_t resource_id,
 860     const struct timespec *budget,
 861     size_t *nbytes);
 862
 863 /**
 864  * fna_network_get_min_effective_budget()
 865  *
 866  * This operation gets the minimum effective budget for a network. Each message
 867  * consumes a contracted budget in "chunks" (i.e: packets) that we call
 868  * minimum effective budget.
 869  *
 870  * A negotiated contract, for N bytes in a period T, means that there is a
 871  * virtual resource that reserves for the user:
 872  *
 873  *   Ceiling ((N bytes) / budget_to_bytes (min_effective_budget)) "CHUNKS"
 874  *
 875  * Note that if the user decides not to send these N bytes at once but, say,
 876  * one byte at a time, it will consume one "CHUNK" at a time and the reserved
 877  * budget will become exhausted before sending all the bytes.
 878  *
 879  * @param[in] resource_id The network
 880  * @param[out] budget The network budget
 881  *
 882  * @return
 883  *   FNA_NO_ERROR \n
 884  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 885  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 886  *   FNA_ERR_RESOURCE_ID_INVALID: if resource id does not represent
 887  *   a network accessible from the current processing node \n
 888  *   FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
 889  *
 890  **/
 891 int fna_network_get_min_effective_budget
 892    (const frsh_resource_id_t resource_id,
 893     struct timespec *budget);
 894
 895 /*@}*/
 896
 897 #endif // _FNA_H_
 898