frsh_distributed.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 //frsh_distributed.h
  59 //==============================================
  60 //  ******** *******    ********  **      **
  61 //  **///// /**////**  **//////  /**     /**
  62 //  **      /**   /** /**        /**     /**
  63 //  ******* /*******  /********* /**********
  64 //  **////  /**///**  ////////** /**//////**
  65 //  **      /**  //**        /** /**     /**
  66 //  **      /**   //** ********  /**     /**
  67 //  //       //     // ////////   //      //
  68 //
  69 // FRSH(FRescor ScHeduler), pronounced "fresh"
  70 //==============================================
  71 #ifndef _FRSH_DISTRIBUTED_H_
  72 #define _FRSH_DISTRIBUTED_H_
  73
  74 /**
  75  * @file frsh_distributed.h
  76  **/
  77
  78
  79 #include "frsh_distributed_types.h"
  80 #include "frsh_core_types.h"
  81
  82 /**
  83  * @defgroup distributed Distributed module
  84  *
  85  * This module defines the functions and typedefs for use in
  86  * distributed applications.
  87  *
  88  * Each network is identified by its resource_id and FRSH hides its
  89  * characteristics completely.  The type of network is implied with
  90  * its ID via a configuration table defined at compile time.
  91  *
  92  * FRSH uses the "message" as the atomic unit for every exchange.
  93  * Queue sizes are measured in number of pending messages.
  94  *
  95  * FRSH provides a function to calculate the transmision time needed
  96  * for a certain message size in a network as well as the maximum
  97  * message size that can admit.
  98  *
  99  * Note also that package delivery guarantee is protocol dependent.
 100  * For protocols in which the order is no guaranteed, the application
 101  * needs to add extra info to detect possible package disorder.
 102  *
 103  * Summary of typical steps.
 104  *
 105  * 1.  Map (internally in FRSH implementation)
 106  *     -   node--> network_addresses
 107  *     -   network --> resource_id's
 108  *     -   unidirectional communication channel --> stream_id
 109  *     -   other config --> protocol_info.
 110  *
 111  * 2.  In a sending node:
 112  *     2.1. Negotiates a "network contract" per communication channel
 113  *          that is used in the application.  In the contract it is
 114  *          specified:
 115  *          -  frsh_resource_type = FRSH_RT_NETWORK.
 116  *          -  frsh_resource_id = <network id #>
 117  *          -  budget:  Time needed to send the required data per period.
 118  *                 (you can use frsh_netinfo_*() functions for this).
 119  *          -  period:  Period of sendings.
 120  *          -  Queueing info:  How will sends be queued at sendEndpoint.
 121  *          -  Other protocol dependent function in protocol_contract_info.
 122  *     2.2. Create a send_endpoint per any unidirectional stream that will
 123  *          be used in sending
 124  *          resource_id --> the network through which the stream will
 125  *                       flow (this is extra info needed for coherency
 126  *                       with the bind).
 127  *          destinator --> network_address of the destination.
 128  *          stream_id --> the unidirectional communication channel.
 129  *     2.3. Bind the send_endpoint to the network contract negotiated
 130  *          above.
 131  *     2.4. The (processor) sending vres invokes frsh_send_(a)sync() to
 132  *          send the data through the corresponding stream.
 133  *
 134  * 3.  In a receiving node:
 135  *     3.1. Create a receive_endpoint per any unidirectional stream
 136  *          that will be used in receiving.
 137  *     3.2. The processor expecting a reception of message invokes
 138  *          frsh_receive_(a)sync() to read the incoming data.
 139  *
 140  * 4.  When all comunication is finished and the channel is no longer
 141  *     needed the nodes will destroy the send and receive endpoints
 142  *     and the network contract will be canceled.
 143  **/
 144
 145 /**
 146  * frsh_distributed_init(void)
 147  *
 148  * This operation initializes all the installed networks and the structures
 149  * that are necessary for the distributed module. Currently it is called by
 150  * frsh_init so it is not necessary that the user calls it again.
 151  *
 152  *   0: No error \n
 153  *   FRSH_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 154  *
 155  **/
 156 int frsh_distributed_init(void);
 157
 158 //////////////////////////////////////////////////////////////////////
 159 //           CONTRACT ASPECTS
 160 //////////////////////////////////////////////////////////////////////
 161
 162 /**
 163  * @defgroup distcontract Contract Info for Distributed Systems
 164  * @ingroup distributed
 165  *
 166  * These functions help you calculate the needed budget for network
 167  * contracts and also to include protocol dependent info in contract
 168  * parameters.
 169  *
 170  * @{
 171  **/
 172
 173 /**
 174  * frsh_network_get_max_message_size()
 175  *
 176  * This operation gives the maximum number of bytes that can be sent
 177  * at a time through the send function when using the network designated by
 178  * 'resource_id' and sending it to 'destination'.
 179  *
 180  * If the application needs to send bigger messages it will have to
 181  * split them.
 182  *
 183  * Some protocols, like IP, are capable of sending large messages
 184  * (and use fragmentation internally) but other protocols don't.
 185  *
 186  * @param[in] resource_id The network we want the tx time from.
 187  * @param[in] destination The destination address
 188  * @param[out] max_size The maximum number of bytes for each message
 189  *
 190  * @return
 191  *   FRSH_NO_ERROR \n
 192  *   FRSH_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 193  *   FRSH_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 194  *   FRSH_ERR_RESOURCE_ID_INVALID: if resource id does not represent
 195  *   a network accessible from the current processing node \n
 196  *   FRSH_ERR_BAD_ARGUMENT: if pointers are NULL or destination is
 197  *   invalid \n
 198  *
 199  **/
 200 int frsh_network_get_max_message_size
 201    (const frsh_resource_id_t resource_id,
 202     const frsh_network_address_t destination,
 203     size_t *max_size);
 204
 205 /**
 206  * frsh_network_bytes_to_budget()
 207  *
 208  * This operation converts a number of bytes into a temporal budget for
 209  * a specific network. Network overheads are not included here but are
 210  * considered internally when negotiating a specific contract.
 211  *
 212  * @param[in] resource_id The network
 213  * @param[in] nbytes Number of bytes
 214  * @param[out] budget The network budget for nbytes
 215  *
 216  * @return
 217  *   FRSH_NO_ERROR \n
 218  *   FRSH_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 219  *   FRSH_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 220  *   FRSH_ERR_RESOURCE_ID_INVALID: if resource id does not represent
 221  *   a network accessible from the current processing node \n
 222  *   FRSH_ERR_BAD_ARGUMENT: if pointers are NULL or nbytes is less
 223  *   than zero \n
 224  *
 225  **/
 226 int frsh_network_bytes_to_budget
 227    (const frsh_resource_id_t resource_id,
 228     const size_t nbytes,
 229     struct timespec *budget);
 230
 231 /**
 232  * frsh_network_budget_to_bytes()
 233  *
 234  * This operation converts a temporal budget into a number of bytes for
 235  * a specific network. Network overheads are not included.
 236  *
 237  * @param[in] resource_id The network
 238  * @param[in] budget The network budget for nbytes
 239  * @param[out] nbytes Number of bytes
 240  *
 241  * @return
 242  *   FRSH_NO_ERROR \n
 243  *   FRSH_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 244  *   FRSH_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 245  *   FRSH_ERR_RESOURCE_ID_INVALID: if resource id does not represent
 246  *   a network accessible from the current processing node \n
 247  *   FRSH_ERR_BAD_ARGUMENT: if pointers are NULL or budget refers to
 248  *   an invalid time value \n
 249  *
 250  **/
 251 int frsh_network_budget_to_bytes
 252    (const frsh_resource_id_t resource_id,
 253     const struct timespec *budget,
 254     size_t *nbytes);
 255
 256 /**
 257  * frsh_network_get_min_effective_budget()
 258  *
 259  * This operation gets the minimum effective budget for a network. Each message
 260  * consumes a contracted budget in "chunks" (i.e: packets) that we call
 261  * minimum effective budget.
 262  *
 263  * A negotiated contract, for N bytes in a period T, means that there is a
 264  * virtual resource that reserves for the user:
 265  *
 266  *   Ceiling ((N bytes) / budget_to_bytes (min_effective_budget)) "CHUNKS"
 267  *
 268  * Note that if the user decides not to send these N bytes at once but, say,
 269  * one byte at a time, it will consume one "CHUNK" at a time and the reserved
 270  * budget will become exhausted before sending all the bytes.
 271  *
 272  * @param[in] resource_id The network
 273  * @param[out] budget The network budget
 274  *
 275  * @return
 276  *   FRSH_NO_ERROR \n
 277  *   FRSH_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 278  *   FRSH_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 279  *   FRSH_ERR_RESOURCE_ID_INVALID: if resource id does not represent
 280  *   a network accessible from the current processing node \n
 281  *   FRSH_ERR_BAD_ARGUMENT: if pointers are NULL \n
 282  *
 283  **/
 284 int frsh_network_get_min_effective_budget
 285    (const frsh_resource_id_t resource_id,
 286     struct timespec *budget);
 287
 288 /**
 289  * frsh_contract_set_queueing_info()
 290  *
 291  * This function adds queueing parameters that will be used in the
 292  * sendEndpoint when the sendEndpoint is bound to the vres.
 293  **/
 294 int frsh_contract_set_queueing_info(frsh_endpoint_queueing_info_t queueing_info,
 295                                     frsh_contract_t *contract);
 296
 297 /**
 298  * frsh_contract_get_queueing_info()
 299  *
 300  * This function gets the queueing parameters that were specified in
 301  * the network contract.
 302  **/
 303 int frsh_contract_get_queueing_info(const frsh_contract_t *contract,
 304                                     frsh_endpoint_queueing_info_t *queueing_info);
 305
 306 /**
 307  * frsh_contract_set_protocol_info
 308  *
 309  * We add protocol info to the contract
 310  **/
 311 int frsh_contract_set_protocol_info(frsh_protocol_info_t protocol_info,
 312                                     frsh_contract_t *contract);
 313
 314 /**
 315  * frsh_contract_get_protocol_info
 316  *
 317  * We get protocol info from the contract
 318  **/
 319 int frsh_contract_get_protocol_info(frsh_contract_t *contract,
 320                                     frsh_protocol_info_t *protocol_info);
 321
 322 /**
 323  * frsh_contract_marshal
 324  *
 325  * Convert a contract to a sequence of bytes of minimum size so it can
 326  * be sent through the network with the minimum amount of bytes.
 327  *
 328  **/
 329
 330 int frsh_contract_marshal(const frsh_contract_t *contract,
 331                           unsigned char         *buffer,
 332                           const size_t          buffer_size,
 333                           size_t                *size);
 334
 335 /**
 336  * frsh_contract_unmarshal
 337  *
 338  * Convert a sequence of bytes generated by frsh_contract_marshal to a contract
 339  *
 340  **/
 341
 342 int frsh_contract_unmarshal(frsh_contract_t      *contract,
 343                             const unsigned char  *marshal_bytes,
 344                             const size_t         size);
 345
 346 /*@}*/
 347
 348 //////////////////////////////////////////////////////////////////////
 349 //           TRANSMISSION SERVICES
 350 //////////////////////////////////////////////////////////////////////
 351
 352 /**
 353  * @defgroup txservices Transmission services
 354  * @ingroup distributed
 355  *
 356  * These functions allow to create and manage endpoints for sending
 357  * and receiving and to perform send and receive operations both
 358  * synchronously (blocking) and asynchronously (non-blocking).
 359  *
 360  * @{
 361  **/
 362
 363
 364 /**
 365  * frsh_send_endpoint_create()
 366  *
 367  * This operation creates a unidirectional stream input endpoint
 368  * through which, after the corresponding binding, it is possible to
 369  * send data to a unicast or multicast destination.
 370  *
 371  * @param[in] resource_id  Identifier of the network referred in the
 372  *                        network contract as a resource_id.
 373  * @param[in] destination    FRSH abstraction of the protocol address for the
 374  *                        destinator node.
 375  * @param[in] stream_id   Identifier of the communication channel between
 376  *                        the nodes.  Multiplexing is achieved by using
 377  *                        different streams between the same nodes and the
 378  *                        same network.
 379  * @param[in] queueing_info Queueing params of the endpoint (size and
 380  *                           policy).
 381  * @param[in] protocol_info Optional protocol-dependent info.
 382  * @param[out] endpoint   Placeholder for the endpoint object.
 383  **/
 384 int frsh_send_endpoint_create
 385         (frsh_resource_id_t     resource_id,
 386          frsh_network_address_t    destination,
 387          frsh_stream_id_t       stream_id,
 388          frsh_send_endpoint_protocol_info_t protocol_info,
 389          frsh_send_endpoint_t  *endpoint);
 390
 391 /**
 392  * frsh_send_endpoint_get_params()
 393  *
 394  * This operation returns in the variables associated to the
 395  * endpoint at creation time.
 396  **/
 397 int frsh_send_endpoint_get_params
 398     (const frsh_send_endpoint_t  endpoint,
 399      frsh_resource_id_t        *resource_id,
 400      frsh_network_address_t       *destination,
 401      frsh_stream_id_t          *stream,
 402      frsh_send_endpoint_protocol_info_t  *protocol_info);
 403
 404 /**
 405  * frsh_send_endpoint_destroy()
 406  *
 407  * This operation eliminates any resources reserved for the referenced
 408  * endpoint.  Pending messages will be discarded and processor-vres
 409  * waiting in a synchronous operation will be awoken with an error
 410  * code.
 411  **/
 412 int frsh_send_endpoint_destroy
 413      (frsh_send_endpoint_t  endpoint);
 414
 415
 416 /**
 417  * frsh_send_endpoint_bind()
 418  *
 419  * This operation associates a send endpoint with a network vres,
 420  * which means that messages sent through this endpoint will consume
 421  * the vres's reserved bandwidth and its packets will be sent
 422  * according to the contract established for that vres.
 423  *
 424  * If the endpoint is already bound to another vres, it is effectively
 425  * unbound from it and bound to the specified one.  However if a vres
 426  * is already bound to another endpoint an error is returned.
 427  *
 428  * A consistency check is done in which the resource_id specified at
 429  * endpoint creation must correspond to the resource_id of the vres
 430  * contract.
 431  *
 432  * @return  0 if successful \n
 433  *      FRSH_ERR_BAD_ARGUMENT if the endpoint or the vres are not
 434  *                            valid \n
 435  *      FRSH_ERR_ALREADY_BOUND if the vres is already bound to some
 436  *                               other send endpoint \n
 437  *      FRSH_ERR_WRONG_NETWORK if the vres network id is not the same
 438  *                               as the one in the endpoint \n
 439  **/
 440 int frsh_send_endpoint_bind
 441   (frsh_vres_id_t      vres,
 442    frsh_send_endpoint_t  endpoint);
 443
 444 /**
 445  * frsh_send_endpoint_unbind()
 446  *
 447  * This operation unbinds a send endpoint from a vres. Endpoints with
 448  * no vres associated cannot be used to send data, and they stay in
 449  * that state  until they are either eliminated or bound again.
 450  *
 451  * @return 0 if successful \n
 452  *         FRSH_ERR_NOT_BOUND if the endpoint was not bound \n
 453  **/
 454 int frsh_send_endpoint_unbind
 455   (frsh_send_endpoint_t  endpoint);
 456
 457 /**
 458  * frsh_send_endpoint_get_vres_id()
 459  *
 460  * This operation copies the id of the vres that is bound to the
 461  * specified send endpoint into the variable pointed to by vres.
 462  *
 463  * @return 0 if successful \n
 464  *         FRSH_ERR_NOT_BOUND if the endpoint was not bound \n
 465  *         FRSH_ERR_BAD_ARGUMENT if the endpoint is not valid or vres
 466  *                               is NULL \n
 467  **/
 468 int frsh_send_endpoint_get_vres_id
 469   (const frsh_send_endpoint_t  endpoint,
 470    frsh_vres_id_t            *vres);
 471
 472 /**
 473  * frsh_send_async()
 474  *
 475  * This operation sends a message stored in msg and of length size
 476  * through the given endpoint. The operation is non-blocking and
 477  * returns immediately.
 478  *
 479  * An internal frsh service will schedule the sending of messages and
 480  * implement the communications sporadic vres  corresponding to the
 481  * network vres bound to the given endpoint.
 482  *
 483  * @returns 0 if successful \n
 484  *       FRSH_ERR_BAD_ARGUMENT if endpoint is not valid \n
 485  *       FRSH_ERR_NOT_BOUND if endpoint is not bound to a valid vres \n
 486  *       FRSH_ERR_TOO_LARGE if the message is too large for the
 487  *                             network protocol \n
 488  *       FRSH_ERR_BUFFER_FULL if the message has been discarded
 489  *                            because the queue is full (and does not
 490  *                            have the policy FRSH_QP_OLDEST \n
 491  **/
 492 int frsh_send_async
 493   (const frsh_send_endpoint_t  endpoint,
 494    const void                  *msg,
 495    const size_t                size);
 496
 497 /**
 498  * frsh_send_sync()
 499  *
 500  * Similar to previous function but now the sending vres gets blocked
 501  * until the message is processed.
 502  **/
 503 int frsh_send_sync
 504   (const frsh_send_endpoint_t endpoint,
 505    void                       *msg,
 506    size_t                      size);
 507
 508 /**
 509  * frsh_send_endpoint_get_status()
 510  *
 511  * This function tells the number of messages still pending in the
 512  * endpoint queue, whether the network is up or down with some
 513  * optional information which is protocol_dependent.
 514  **/
 515 int frsh_send_endpoint_get_status
 516         (const frsh_send_endpoint_t endpoint,
 517          int *number_pending_msg,
 518          frsh_endpoint_network_status_t *network_status,
 519          frsh_protocol_status_t *protocol_status);
 520
 521 /**
 522  * frsh_receive_endpoint_create()
 523  *
 524  * This operation creates a receive endpoint associated with a
 525  * undirectional stream within a network interface of the node.
 526  *
 527  * Receiving endpoints are not bound to any network vres, this is
 528  * because don't originate any traffic.
 529  *
 530  * Note that the protocol address is not needed for reception because
 531  * it can be determined internally by FRSH based on the resource_id.
 532  *
 533  * Note also that messages may come from diferent originators.
 534  *
 535  * @param[in] resource_id  Id of the network from which we listen.
 536  * @param[in] stream_id  Id of the stream within the network.
 537  * @param[in] queueing_info Buffering information(queue size and
 538  *                          policy).
 539  * @param[in] protocol_info Extra protocol info opaque for the
 540  *                          application.
 541  * @param[in] endpoin  Placeholder for the endpoint object.
 542  *
 543  * @return 0 if successful \n
 544  *   FRSH_ERR_BAD_ARGUMENT if the stream or the network id are not
 545  *      valid \n
 546  **/
 547 int frsh_receive_endpoint_create
 548   (frsh_resource_id_t        resource_id,
 549    frsh_stream_id_t          stream_id,
 550    frsh_endpoint_queueing_info_t queueing_info,
 551    frsh_receive_endpoint_protocol_info_t protocol_info,
 552    frsh_receive_endpoint_t  *endpoint);
 553
 554 /**
 555  * frsh_receive_endpoint_get_params()
 556  *
 557  * This operation returns in the variables associated to the
 558  * endpoint at creation time.
 559  **/
 560 int frsh_receive_endpoint_get_params
 561      (const frsh_receive_endpoint_t  endpoint,
 562      frsh_resource_id_t        *resource_id,
 563      frsh_stream_id_t          *stream,
 564      frsh_endpoint_queueing_info_t   *queueing_info,
 565      frsh_receive_endpoint_protocol_info_t   *protocol_info);
 566
 567 /**
 568  * frsh_receive_endpoint_destroy()
 569  *
 570  * This operation eliminates any resources reserved for the referenced
 571  * endpoint.  Pending messages will be discarded and processor-vres
 572  * waiting in a synchronous operation will be awoken with an error
 573  * code.
 574  **/
 575 int frsh_receive_endpoint_destroy
 576      (frsh_receive_endpoint_t  endpoint);
 577
 578
 579 /**
 580  * frsh_receive_sync()
 581  *
 582  * If there are no messages available in the specified receive endpoint
 583  * this operation blocks the calling thread waiting for a message to be
 584  * received.
 585  *
 586  * When a message is available, if its size is less than or
 587  * equal to the buffer_size, the function stores it in the variable
 588  * pointed to by buffer and puts the number of bytes received in the
 589  * variable pointed to by message size.
 590  *
 591  * The function fails with FRSH_ERR_NO_SPACE if the buffersize is
 592  * too small for the message received.  In this case the message is
 593  * lost.
 594  *
 595  * Messages arriving at a destination buffer that is full will be
 596  * silently discarded (details in the queueing policy of the
 597  * endpoint). The application is responsible of reading the receive
 598  * endpoints with appropriate regularity, or of using a sequence
 599  * number or some other mechanism to detect any lost messages.
 600  *
 601  * @return 0 if successful \n
 602  *     FRSH_ERR_BAD_ARGUMENT if the endpoint is not valid, or if
 603  *       buffer or message_size are NULL.\n
 604  *     FRSH_ERR_NO_SPACE if the message size is bigger than the
 605  *       provided buffer \n
 606  **/
 607 int frsh_receive_sync
 608   (const frsh_receive_endpoint_t  endpoint,
 609    void                           *buffer,
 610    size_t                         buffer_size,
 611    size_t                         *message_size,
 612    frsh_network_address_t         *from);
 613
 614 /**
 615  * frsh_receive_async()
 616  *
 617  * This operation is similar to the previous one but it works in a non
 618  * blocking (asynchronous) fashion.  If no message is available it
 619  * returns with error FRSH_NO_MESSAGE.
 620  *
 621  * @return 0 if successful \n
 622  *     FRSH_ERR_BAD_ARGUMENT if the endpoint is not valid, or if
 623  *       buffer or message_size are NULL \n
 624  *     FRSH_NO_MESSAGE if no messages are available in the queue \n
 625  *     FRSH_ERR_NO_SPACE if the message size is bigger than the
 626  *       provided buffer \n
 627  **/
 628 int frsh_receive_async
 629   (const frsh_receive_endpoint_t  endpoint,
 630    void                           *buffer,
 631    size_t                         buffer_size,
 632    size_t                         *message_size,
 633    frsh_network_address_t         *from);
 634
 635
 636 /**
 637  * frsh_receive_endpoint_get_status
 638  *
 639  * This function tells the number of messages still pending in the
 640  * endpoint queue, whether the network is up or down and some optional
 641  * information which is protocol dependent.
 642  **/
 643 int frsh_receive_endpoint_get_status
 644         (const frsh_receive_endpoint_t endpoint,
 645          int *number_pending_messages,
 646          frsh_endpoint_network_status_t *network_status,
 647          frsh_protocol_status_t *protocol_status);
 648
 649 /*@}*/
 650
 651 #endif // _FRSH_DISTRIBUTED_H_