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_vres_create()
 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  * In object oriented terminology it is similar to a constructor of the
 158  * virtual resource class.
 159  *
 160  * If the on-line admission test is enabled, it determines whether the
 161  * contract can be admitted or not based on the current contracts
 162  * established in the network. Then it creates the vres and
 163  * recalculates all necessary parameters for the contracts already
 164  * present in the system.
 165  *
 166  * This is a potentially blocking operation, it returns when the
 167  * system has either rejected the contract, or admitted it and made it
 168  * effective.
 169  *
 170  * @param[in] resource_id The network we are referring to (a protocol
 171  * could be able to handle several networks at the same time)
 172  * @param[in] contract  The contract parameters to negotiate
 173  * @param[out] vres The internal virtual resource id
 174  *
 175  * @return
 176  *   FNA_NO_ERROR: in this case it also means contract accepted \n
 177  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 178  *   FNA_ERR_TOO_MANY_VRES: if there is no space for more vres \n
 179  *   FNA_ERR_CONTRACT_ID_ALREADY_EXISTS: contract_id is not unique \n
 180  *   FNA_ERR_CONTRACT_REJECTED: if the contract is not accepted \n
 181  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 182  *   FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
 183  *   FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
 184  *
 185  **/
 186 int fna_vres_create
 187       (const frsh_resource_id_t resource_id,
 188        const frsh_contract_t *contract,
 189        fna_vres_id_t *vres);
 190
 191 /**
 192  * fna_vres_renegotiate_sync()
 193  *
 194  * The operation renegotiates a contract for an existing vres. If
 195  * the on-line admission test is enabled it determines whether the
 196  * contract can be admitted or not based on the current contracts
 197  * established in the system. If it cannot be admitted, the old
 198  * contract remains in effect and an error is returned. If it can be
 199  * admitted, it recalculates all necessary parameters for the
 200  * contracts already present in the system and returns zero. This is a
 201  * potentially blocking operation; it returns when the system has
 202  * either rejected the new contract, or admitted it and made it
 203  * effective.
 204  *
 205  * @param[in] resource_id The network we are referring to (a protocol
 206  * could be able to handle several networks at the same time)
 207  * @param[in] vres The internal virtual resource id to renegotiate
 208  * @param[in] new_contract The new contract
 209  *
 210  *  @return
 211  *   FNA_NO_ERROR: in this case it also means contract accepted \n
 212  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 213  *   FNA_ERR_NOT_CONTRACTED_VRES: if the vres is not contracted \n
 214  *   FNA_ERR_CONTRACT_ID_ALREADY_EXISTS: contract_id is not unique \n
 215  *   FNA_ERR_CONTRACT_REJECTED: if the contract is not accepted \n
 216  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 217  *   FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
 218  *   FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
 219  *
 220  **/
 221 int fna_vres_renegotiate_sync
 222       (const frsh_resource_id_t resource_id,
 223        const fna_vres_id_t vres,
 224        const frsh_contract_t *new_contract);
 225
 226 /**
 227  * fna_vres_renegotiate_async()
 228  *
 229  * The operation enqueues a renegotiate operation for an existing
 230  * vres, and returns immediately. The renegotiate operation is
 231  * performed asynchronously, as soon as it is practical; meanwhile the
 232  * system operation will continue normally. When the renegotiation is
 233  * made, if the on-line admission test is enabled it determines
 234  * whether the contract can be admitted or not based on the current
 235  * contracts established in the system. If it cannot be admitted, the
 236  * old contract remains in effect. If it can be admitted, it
 237  * recalculates all necessary parameters for the contracts already
 238  * present in the system.
 239  *
 240  * When the operation is completed, notification is made to the
 241  * caller, if requested, via a signal. The status of the operation (in
 242  * progress, admitted, rejected) can be checked with the
 243  * frsh_vres_get_renegotiation_status() operation.  The argument
 244  * sig_notify can be FRSH_NULL_SIGNAL (no notification), or any FRSH
 245  * signal value and in this case signal_info is to be sent with the signal.
 246  *
 247  * @param[in] resource_id The network we are referring to (a protocol
 248  * could be able to handle several networks at the same time)
 249  * @param[in] vres The internal virtual resource id to renegotiate
 250  * @param[in] new_contract The new contract
 251  * @param[in] signal_to_notify  Signal number to use to notify vres of
 252  * the negotiation result. If FRSH_NULL_SIGNAL,  no signal will be raised.
 253  * @param[in] signal_info: Associated info that will come with the signal.
 254  * This parameter will be ignored if signal_to_notify == FRSH_NULL_SIGNAL.
 255  *
 256  * @return
 257  *   FNA_NO_ERROR: in this case it also means contract accepted \n
 258  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 259  *   FNA_ERR_NOT_CONTRACTED_VRES: if the vres is not contracted \n
 260  *   FNA_ERR_CONTRACT_ID_ALREADY_EXISTS: contract_id is not unique \n
 261  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 262  *   FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
 263  *   FNA_ERR_BAD_ARGUMENT: if pointers are NULL, or sig_notify is neither
 264  *      NULL nor a valid POSIX signal \n
 265  *
 266  **/
 267 int fna_vres_renegotiate_async
 268       (const frsh_resource_id_t resource_id,
 269        const fna_vres_id_t vres,
 270        const frsh_contract_t *new_contract,
 271        frsh_signal_t signal_to_notify,
 272        frsh_signal_info_t signal_info);
 273
 274 /**
 275  * fna_vres_get_renegotiation_status()
 276  *
 277  * The operation reports on the status of the last renegotiation
 278  * operation enqueued for the specified vres. It is callable even
 279  * after notification of the completion of such operation, if
 280  * requested.
 281  *
 282  * If the vres is not and has not been involved in any of the
 283  * frsh_contract_renegotiate_async() or frsh_group_change_mode_async()
 284  * operations, the status returned is FNA_NOT_REQUESTED
 285  *
 286  * @param[in] resource_id The network we are referring to (a protocol
 287  * could be able to handle several networks at the same time)
 288  * @param[in] vres The internal virtual resource id we want the status from
 289  * @param[in] renegotiation_status The status of the last renegotiation on
 290  * vres (FRSH_RS_IN_PROGRESS, FRSH_RS_REJECTED, FRSH_RS_ADMITTED,
 291  * FRSH_RS_NOT_REQUESTED)
 292  *
 293  * @return
 294  *   FNA_NO_ERROR: in this case it also means contract accepted \n
 295  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 296  *   FNA_ERR_NOT_CONTRACTED_VRES: if the vres is not contracted \n
 297  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 298  *   FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
 299  *   FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
 300  *
 301  **/
 302 int fna_vres_get_renegotiation_status
 303       (const frsh_resource_id_t resource_id,
 304        const fna_vres_id_t vres,
 305        frsh_renegotiation_status_t *renegotiation_status);
 306
 307 /**
 308  * fna_vres_destroy()
 309  *
 310  * The operation eliminates the specified vres
 311  * and recalculates all necessary parameters for the contracts
 312  * remaining in the system. This is a potentially blocking operation;
 313  * it returns when the system has made the changes effective.
 314  *
 315  * @param[in] resource_id The network we are referring to (a protocol
 316  * could be able to handle several networks at the same time)
 317  * @param[in] vres The internal virtual resource id to destroy
 318  *
 319  * @return
 320  *   FNA_NO_ERROR: in this case it also means contract accepted \n
 321  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 322  *   FNA_ERR_NOT_CONTRACTED_VRES: if the vres is not contracted \n
 323  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 324  *   FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
 325  *   FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
 326  *
 327  **/
 328 int fna_vres_destroy
 329       (const frsh_resource_id_t resource_id,
 330        const fna_vres_id_t vres);
 331
 332 /**
 333  * fna_vres_get_contract()
 334  *
 335  * This operation stores the contract parameters currently associated
 336  * with the specified vres in the variable pointed to by
 337  * contract. It returns an error if the vres_id is not recognised.
 338  *
 339  * @param[in] resource_id The network we are referring to (a protocol
 340  * could be able to handle several networks at the same time)
 341  * @param[in] vres The internal virtual resource id
 342  * @param[out] contract  The contract parameters that we want
 343  *
 344  * @return
 345  *   FNA_NO_ERROR: in this case it also means contract accepted \n
 346  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 347  *   FNA_ERR_NOT_CONTRACTED_VRES: if the vres is not contracted \n
 348  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 349  *   FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
 350  *   FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
 351  *
 352  **/
 353 int fna_vres_get_contract
 354       (const frsh_resource_id_t resource_id,
 355        const fna_vres_id_t vres,
 356        frsh_contract_t *contract);
 357
 358 /**
 359  * fna_vres_get_usage()
 360  *
 361  * This function gets the execution time spent by all messages that have been
 362  * sent through the specified vres.
 363  *
 364  * @param[in] resource_id The network we are referring to (a protocol
 365  * could be able to handle several networks at the same time)
 366  * @param[in] vres The internal virtual resource id
 367  * @param[out] usage  Execution time spent by this vres
 368  *
 369  * @return
 370  *   FNA_NO_ERROR: in this case it also means contract accepted \n
 371  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 372  *   FNA_ERR_NOT_CONTRACTED_VRES: if the vres is not contracted \n
 373  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 374  *   FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
 375  *   FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
 376  *
 377  **/
 378 int fna_vres_get_usage
 379       (const frsh_resource_id_t resource_id,
 380        const fna_vres_id_t vres,
 381        struct timespec *usage);
 382
 383 /**
 384  * fna_vres_get_remaining_budget()
 385  *
 386  * This function stores in the variable pointed to by budget the
 387  * remaining execution-time budget associated with the specified
 388  * vres in the present period.
 389  *
 390  * @param[in] resource_id The network we are referring to (a protocol
 391  * could be able to handle several networks at the same time)
 392  * @param[in] vres The internal virtual resource id
 393  * @param[out] remaining_budget  The remaining budget for this period
 394  *
 395  *  @return
 396  *   FNA_NO_ERROR: in this case it also means contract accepted \n
 397  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 398  *   FNA_ERR_NOT_CONTRACTED_VRES: if the vres is not contracted \n
 399  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 400  *   FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
 401  *   FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
 402  *
 403  **/
 404 int fna_vres_get_remaining_budget
 405       (const frsh_resource_id_t resource_id,
 406        const fna_vres_id_t vres,
 407        struct timespec *remaining_budget);
 408
 409 /**
 410  * fna_vres_get_budget_and_period()
 411  *
 412  * This function gets the budget and period associated with the specified vres
 413  * for each period. If one of these pointers is NULL, the corresponding
 414  * information is not stored.
 415  *
 416  * @param[in] resource_id The network we are referring to (a protocol
 417  * could be able to handle several networks at the same time)
 418  * @param[in] vres The internal virtual resource id
 419  * @param[out] budget The budget associated to vres
 420  * @param[out] period  The period associated to vres
 421  *
 422  * @return
 423  *   FNA_NO_ERROR: in this case it also means contract accepted \n
 424  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 425  *   FNA_ERR_NOT_CONTRACTED_VRES: if the vres is not contracted \n
 426  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 427  *   FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
 428  *   FNA_ERR_BAD_ARGUMENT: if both pointers are NULL \n
 429  *
 430  **/
 431 int fna_vres_get_budget_and_period
 432       (const frsh_resource_id_t resource_id,
 433        const fna_vres_id_t vres,
 434        struct timespec *budget,
 435        struct timespec *period);
 436
 437 /*@}*/
 438
 439 ///////////////////////////////////////////////////////////////////
 440 //           SPARE CAPACITY FUNCIONS
 441 ///////////////////////////////////////////////////////////////////
 442
 443 /**
 444  * @defgroup fnaspare FNA Spare Capacity
 445  * @ingroup fna
 446  *
 447  * The following functions are used to get spare capacity data
 448  *
 449  * @{
 450  **/
 451
 452 /**
 453  * fna_resource_get_capacity()
 454  *
 455  * This operation gets the spare capacity currently assigned to a importance
 456  * level. If we divide this value by UINT32_MAX we will get the network
 457  * utilization associated to the spare capacity of a importance level.
 458  *
 459  * The following is typically in stdint.h: \n
 460  *  - typedef unsigned int uint32_t;  \n
 461  *  - # define UINT32_MAX  (4294967295U)  \n
 462  *
 463  * @param[in] resource_id The network we are referring to (a protocol
 464  * could be able to handle several networks at the same time)
 465  * @param[in] importance The importance we want the capacity of
 466  * @param[out] capacity The spare capacity for that importance level
 467  *
 468  * @return
 469  *   FNA_NO_ERROR: in this case it also means contract accepted \n
 470  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 471  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 472  *   FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
 473  *   FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
 474  *
 475  **/
 476 int fna_resource_get_capacity
 477       (const frsh_resource_id_t resource_id,
 478        const int importance,
 479        uint32_t *capacity);
 480
 481 /**
 482  * fna_resource_get_total_weight()
 483  *
 484  * This function gets the sum of the weight parameters for all vres in a
 485  * network of an importance level.
 486  *
 487  * @param[in] resource_id The network we are referring to (a protocol
 488  * could be able to handle several networks at the same time)
 489  * @param[in] importance The importance we want the total weight of
 490  * @param[out] total_weight The total weight for that importance level
 491  *
 492  * @return
 493  *   FNA_NO_ERROR: in this case it also means contract accepted \n
 494  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 495  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 496  *   FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
 497  *   FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
 498  *
 499  **/
 500 int fna_resource_get_total_weight
 501       (const frsh_resource_id_t resource_id,
 502        const int importance,
 503        int *total_weight);
 504
 505 /**
 506  * fna_vres_decrease_capacity()
 507  *
 508  * This function allows to ask for less budget and period than what we
 509  * received. The request must be compatible with the rest of contract
 510  * parameters of the vres. If we want to recover the released capacity
 511  * we will need to renegotiate.
 512  *
 513  * @param[in] resource_id The network we are referring to (a protocol
 514  * could be able to handle several networks at the same time)
 515  * @param[in] vres The internal virtual resource id
 516  * @param[in] new_budget The new_budget
 517  * @param[in] new_period The new Period
 518  *
 519  * @return
 520  *   FNA_NO_ERROR: in this case it also means contract accepted \n
 521  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 522  *   FNA_ERR_NOT_CONTRACTED_VRES: if the vres is not contracted \n
 523  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 524  *   FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
 525  *   FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
 526  *   FNA_ERR_CONTRACT_REJECTED: if it is incompatible with the current
 527  *      contract \n
 528  *
 529  **/
 530 int fna_vres_decrease_capacity
 531       (const frsh_resource_id_t resource_id,
 532        const fna_vres_id_t vres,
 533        const struct timespec new_budget,
 534        const struct timespec new_period);
 535
 536 /*@}*/
 537
 538 ///////////////////////////////////////////////////////////////////
 539 //           SEND RECEIVE OPERATIONS
 540 ///////////////////////////////////////////////////////////////////
 541
 542 /**
 543  * @defgroup fnasendrecv FNA Send and Receive
 544  * @ingroup fna
 545  *
 546  * The following functions are used to send and receive
 547  *
 548  * @{
 549  **/
 550
 551 /**
 552  * fna_send_sync()
 553  *
 554  * Similar to previous function but now the sending thread gets blocked
 555  * until the message is already sent to the network.
 556  *
 557  * @param[in] endpoint The send endpoint we are sending through. It must
 558  *    be bound to a virtual resource (resource_id is in the endpoint).
 559  * @param[in] msg The message we want to send
 560  * @param[in] size The size in bytes of the message
 561  *
 562  * @returns
 563  *   FNA_NO_ERROR: in this case it also means contract accepted \n
 564  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 565  *   FNA_ERR_NOT_BOUND: if endpoint is not bound to a valid vres \n
 566  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 567  *   FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
 568  *   FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
 569  *   FNA_ERR_TOO_LARGE: if the message is too large for the network protocol \n
 570  *   FNA_ERR_BUFFER_FULL: if the message has been discarded because
 571  *   the queue is full (and does not have the policy FNA_QP_OLDEST) \n
 572  *
 573  **/
 574 int fna_send_sync
 575       (const frsh_send_endpoint_t *endpoint,
 576        const void *msg,
 577        const size_t size);
 578
 579 /**
 580  * fna_send_async()
 581  *
 582  * This operation sends a message stored in msg and of length size
 583  * through the given send endpoint. The operation is non-blocking and
 584  * returns immediately.
 585  *
 586  * @param[in] endpoint The send endpoint we are sending through. It must
 587  *    be bound to a virtual resource (resource_id is in the endpoint).
 588  * @param[in] msg The message we want to send
 589  * @param[in] size The size in bytes of the message
 590  *
 591  * @returns
 592  *   FNA_NO_ERROR: in this case it also means contract accepted \n
 593  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 594  *   FNA_ERR_NOT_BOUND: if endpoint is not bound to a valid vres \n
 595  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 596  *   FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
 597  *   FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
 598  *   FNA_ERR_TOO_LARGE: if the message is too large for the network protocol \n
 599  *   FNA_ERR_BUFFER_FULL: if the message has been discarded because
 600  *   the queue is full (and does not have the policy FNA_QP_OLDEST) \n
 601  *
 602  **/
 603 int fna_send_async
 604       (const frsh_send_endpoint_t *endpoint,
 605        const void *msg,
 606        const size_t size);
 607
 608 /**
 609  * fna_receive_sync()
 610  *
 611  * This operation is used to receive messages from the network with a
 612  * blocking behavior (if there are no messages this operation blocks
 613  * the calling thread).
 614  *
 615  * When a message is available, it is copied to buffer (up to its size).
 616  * The number of bytes copied is returned in received_bytes. The rest
 617  * of the bytes of that message will be lost or not depending on the
 618  * protocol (FNA_ERR_NO_SPACE will be returned if it is).
 619  *
 620  * The function fails with FNA_ERR_NO_SPACE if the buffersize is
 621  * too small for the message received.  In this case the message is
 622  * lost.
 623  *
 624  * Messages arriving at a receiver buffer that is full will be handled
 625  * according to the queueing policy of the endpoint (overwrite oldest,
 626  * discard it,etc).
 627  *
 628  * @param[in] endpoint The receive endpoint we are receiving from.
 629  *    (resource_id is in the endpoint).
 630  * @param[out] buffer Buffer for storing the received message
 631  * @param[in] buffer_size The size in bytes of this buffer
 632  * @param[out] received_bytes The actual number of received bytes
 633  *
 634  * @return
 635  *   FNA_NO_ERROR: in this case it also means contract accepted \n
 636  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 637  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 638  *   FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
 639  *   FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
 640  *   FNA_ERR_NO_SPACE: if the message size is bigger than the
 641  *      provided buffer. \n
 642  *
 643  **/
 644 int fna_receive_sync
 645       (const frsh_receive_endpoint_t *endpoint,
 646        void *buffer,
 647        const size_t buffer_size,
 648        size_t *received_bytes);
 649
 650 /**
 651  * fna_receive_async()
 652  *
 653  * This operation is similar to the previous one but it works in a non
 654  * blocking (asynchronous) fashion.  If no message is available it
 655  * returns with error FNA_NO_MESSAGE.
 656  *
 657  * @param[in] endpoint The receive endpoint we are receiving from.
 658  *    (resource_id is in the endpoint).
 659  * @param[out] buffer Buffer for storing the received message
 660  * @param[in] buffer_size The size in bytes of this buffer
 661  * @param[out] received_bytes The actual number of received bytes
 662  *
 663  * @return
 664  *   FNA_NO_ERROR: in this case it also means contract accepted \n
 665  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 666  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 667  *   FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
 668  *   FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
 669  *   FNA_ERR_NO_SPACE: if the message size is bigger than the
 670  *      provided buffer. \n
 671  *   FNA_NO_MESSAGE: if no messages are available in the queue. \n
 672  *
 673  **/
 674 int fna_receive_async
 675       (const frsh_receive_endpoint_t *endpoint,
 676        void *buffer,
 677        const size_t buffer_size,
 678        size_t *received_bytes);
 679
 680 /**
 681  * fna_send_endpoint_get_status()
 682  *
 683  * This function tells the number of messages still pending in the
 684  * endpoint queue, whether the network is up or down with some
 685  * optional information which is protocol_dependent.
 686  *
 687  * @param[in] endpoint The send endpoint (resource_id is in the endpoint).
 688  * @param[out] number_of_pending_messages The number of pending messages
 689  * @param[out] network_status How is the network (up, down..)
 690  * @param[out] protocol_status Protocol dependent status info
 691  *
 692  * @return
 693  *   FNA_NO_ERROR: in this case it also means contract accepted \n
 694  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 695  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 696  *   FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
 697  *   FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
 698  *
 699  **/
 700 int fna_send_endpoint_get_status(const frsh_send_endpoint_t *endpoint,
 701                                  int *number_of_pending_messages,
 702                                  frsh_endpoint_network_status *network_status,
 703                                  frsh_protocol_status_t *protocol_status);
 704
 705 /**
 706  * fna_receive_endpoint_create()
 707  *
 708  * This operation creates a receive endpoint associated with a
 709  * undirectional stream within a network interface of the node.
 710  *
 711  * Receiving endpoints are not bound to any network vres, this is
 712  * because don't originate any traffic.
 713  *
 714  * Note that the protocol address is not needed for reception because
 715  * it can be determined internally by FRSH based on the network_id.
 716  *
 717  * Note also that messages may come from diferent originators.
 718  *
 719  * @param[in] resource_id  Id of the network from which we listen.
 720  * @param[in] stream_id  Id of the stream within the network.
 721  * @param[in] queueing_info Buffering information(queue size and
 722  *                          policy).
 723  * @param[in] protocol_info Extra protocol info opaque for the
 724  *                          application.
 725  * @param[out] endpoint  Placeholder for the endpoint object.
 726  *
 727  * @return
 728  *   FNA_NO_ERROR: in this case it also means contract accepted \n
 729  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 730  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 731  *   FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
 732  *   FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
 733  **/
 734 int fna_receive_endpoint_create
 735       (const frsh_resource_id_t resource_id,
 736        const frsh_stream_id_t stream_id,
 737        const frsh_endpoint_queueing_info_t queueing_info,
 738        const frsh_protocol_info_t protocol_info,
 739        frsh_receive_endpoint_t *endpoint);
 740
 741 /**
 742  * fna_receive_endpoint_get_pending_messages
 743  *
 744  * This function tells the number of messages still pending in the
 745  * endpoint queue, whether the network is up or down and some optional
 746  * information which is protocol dependent.
 747  *
 748  * @param[in] endpoint The receive endpoint (resource_id is in the endpoint).
 749  * @param[out] number_of_pending_messages The number of pending messages
 750  * @param[out] network_status How is the network (up, down..)
 751  * @param[out] protocol_status Protocol dependent status info
 752  *
 753  * @return
 754  *   FNA_NO_ERROR: in this case it also means contract accepted \n
 755  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 756  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 757  *   FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
 758  *   FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
 759  *
 760  **/
 761 int fna_receive_endpoint_get_status
 762       (const frsh_receive_endpoint_t *endpoint,
 763        int *number_of_pending_messages,
 764        frsh_endpoint_network_status *network_status,
 765        frsh_protocol_status_t *protocol_status);
 766
 767 /*@}*/
 768
 769 //////////////////////////////////////////////////////////////////////
 770 //           NETWORK CONFIGURATION FUNCTIONS
 771 //////////////////////////////////////////////////////////////////////
 772
 773 /**
 774  * @defgroup frshfnaconfig FNA Network Configuration
 775  * @ingroup fna
 776  *
 777  * These functions are needed to set/get some network dependent values
 778  *
 779  * @{
 780  **/
 781
 782 /**
 783  * fna_message_get_tx_time()
 784  *
 785  * This operation gives the physical transmission time that it takes to
 786  * send a message of the nbytes size through the network designated by
 787  * resource_id, not including any network overheads (fragmentation in packets,
 788  * headers, retransmissions,...).
 789  *
 790  * It is be used by the application to calculate the minimum and
 791  * maximum budgets used in the preparation of network contracts.
 792  * (Note that in the negotiation overheads must be taken into account)
 793  *
 794  * @param[in] resource_id The network we want the tx time from.
 795  * @param[in] nbytes Number of bytes of the message
 796  * @param[out] tx_time The transmission time for nbytes (without overheads)
 797  *
 798  * @return
 799  *   FNA_NO_ERROR: in this case it also means contract accepted \n
 800  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 801  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 802  *   FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
 803  *   FNA_ERR_BAD_ARGUMENT: if pointers are NULL or nbytes is bigger than
 804  *     the maximum message size \n
 805  *
 806  **/
 807 int fna_message_get_tx_time
 808       (const frsh_resource_id_t resource_id,
 809        const size_t nbytes,
 810        struct timespec *tx_time);
 811
 812 /**
 813  * fna_message_get_max_size()
 814  *
 815  * This operation gives the maximum number of bytes that can be sent
 816  * in a single message through the network designated by resource_id.
 817  * If the application needs to send bigger messages it will have to
 818  * split them. Some protocols like TCP/IP are capable of sending large
 819  * messages (and use fragmentation internally) but other protocols doesn't
 820  * provide fragmentation features so the maximum size will be the MTU itself.
 821  *
 822  * It is be used by the application to calculate the minimum and
 823  * maximum budgets used in the preparation of network contracts.
 824  *
 825  * @param[in] resource_id The network we want the tx time from.
 826  * @param[out] max_size The maximum number of bytes for each message
 827  *
 828  * @return
 829  *   FNA_NO_ERROR: in this case it also means contract accepted \n
 830  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 831  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 832  *   FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
 833  *   FNA_ERR_BAD_ARGUMENT: if pointers are NULL or nbytes is bigger than
 834  *     the maximum message size \n
 835  *
 836  **/
 837 int fna_message_get_max_size
 838       (const frsh_resource_id_t resource_id,
 839        size_t *max_size);
 840
 841 /*@}*/
 842
 843 #endif // _FNA_H_
 844