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
 324 //////////////////////////////////////////////////////////////////////
 325 //           TRANSMISSION SERVICES
 326 //////////////////////////////////////////////////////////////////////
 327
 328 /**
 329  * @defgroup txservices Transmission services
 330  * @ingroup distributed
 331  *
 332  * These functions allow to create and manage endpoints for sending
 333  * and receiving and to perform send and receive operations both
 334  * synchronously (blocking) and asynchronously (non-blocking).
 335  *
 336  * @{
 337  **/
 338
 339
 340 /**
 341  * frsh_send_endpoint_create()
 342  *
 343  * This operation creates a unidirectional stream input endpoint
 344  * through which, after the corresponding binding, it is possible to
 345  * send data to a unicast or multicast destination.
 346  *
 347  * @param[in] resource_id  Identifier of the network referred in the
 348  *                        network contract as a resource_id.
 349  * @param[in] destination    FRSH abstraction of the protocol address for the
 350  *                        destinator node.
 351  * @param[in] stream_id   Identifier of the communication channel between
 352  *                        the nodes.  Multiplexing is achieved by using
 353  *                        different streams between the same nodes and the
 354  *                        same network.
 355  * @param[in] queueing_info Queueing params of the endpoint (size and
 356  *                           policy).
 357  * @param[in] protocol_info Optional protocol-dependent info.
 358  * @param[out] endpoint   Placeholder for the endpoint object.
 359  **/
 360 int frsh_send_endpoint_create
 361         (frsh_resource_id_t     resource_id,
 362          frsh_network_address_t    destination,
 363          frsh_stream_id_t       stream_id,
 364          frsh_send_endpoint_protocol_info_t protocol_info,
 365          frsh_send_endpoint_t  *endpoint);
 366
 367 /**
 368  * frsh_send_endpoint_get_params()
 369  *
 370  * This operation returns in the variables associated to the
 371  * endpoint at creation time.
 372  **/
 373 int frsh_send_endpoint_get_params
 374     (const frsh_send_endpoint_t  endpoint,
 375      frsh_resource_id_t        *resource_id,
 376      frsh_network_address_t       *destination,
 377      frsh_stream_id_t          *stream,
 378      frsh_send_endpoint_protocol_info_t  *protocol_info);
 379
 380 /**
 381  * frsh_send_endpoint_destroy()
 382  *
 383  * This operation eliminates any resources reserved for the referenced
 384  * endpoint.  Pending messages will be discarded and processor-vres
 385  * waiting in a synchronous operation will be awoken with an error
 386  * code.
 387  **/
 388 int frsh_send_endpoint_destroy
 389      (frsh_send_endpoint_t  endpoint);
 390
 391
 392 /**
 393  * frsh_send_endpoint_bind()
 394  *
 395  * This operation associates a send endpoint with a network vres,
 396  * which means that messages sent through this endpoint will consume
 397  * the vres's reserved bandwidth and its packets will be sent
 398  * according to the contract established for that vres.
 399  *
 400  * If the endpoint is already bound to another vres, it is effectively
 401  * unbound from it and bound to the specified one.  However if a vres
 402  * is already bound to another endpoint an error is returned.
 403  *
 404  * A consistency check is done in which the resource_id specified at
 405  * endpoint creation must correspond to the resource_id of the vres
 406  * contract.
 407  *
 408  * @return  0 if successful \n
 409  *      FRSH_ERR_BAD_ARGUMENT if the endpoint or the vres are not
 410  *                            valid \n
 411  *      FRSH_ERR_ALREADY_BOUND if the vres is already bound to some
 412  *                               other send endpoint \n
 413  *      FRSH_ERR_WRONG_NETWORK if the vres network id is not the same
 414  *                               as the one in the endpoint \n
 415  **/
 416 int frsh_send_endpoint_bind
 417   (frsh_vres_id_t      vres,
 418    frsh_send_endpoint_t  endpoint);
 419
 420 /**
 421  * frsh_send_endpoint_unbind()
 422  *
 423  * This operation unbinds a send endpoint from a vres. Endpoints with
 424  * no vres associated cannot be used to send data, and they stay in
 425  * that state  until they are either eliminated or bound again.
 426  *
 427  * @return 0 if successful \n
 428  *         FRSH_ERR_NOT_BOUND if the endpoint was not bound \n
 429  **/
 430 int frsh_send_endpoint_unbind
 431   (frsh_send_endpoint_t  endpoint);
 432
 433 /**
 434  * frsh_send_endpoint_get_vres_id()
 435  *
 436  * This operation copies the id of the vres that is bound to the
 437  * specified send endpoint into the variable pointed to by vres.
 438  *
 439  * @return 0 if successful \n
 440  *         FRSH_ERR_NOT_BOUND if the endpoint was not bound \n
 441  *         FRSH_ERR_BAD_ARGUMENT if the endpoint is not valid or vres
 442  *                               is NULL \n
 443  **/
 444 int frsh_send_endpoint_get_vres_id
 445   (const frsh_send_endpoint_t  endpoint,
 446    frsh_vres_id_t            *vres);
 447
 448 /**
 449  * frsh_send_async()
 450  *
 451  * This operation sends a message stored in msg and of length size
 452  * through the given endpoint. The operation is non-blocking and
 453  * returns immediately.
 454  *
 455  * An internal frsh service will schedule the sending of messages and
 456  * implement the communications sporadic vres  corresponding to the
 457  * network vres bound to the given endpoint.
 458  *
 459  * @returns 0 if successful \n
 460  *       FRSH_ERR_BAD_ARGUMENT if endpoint is not valid \n
 461  *       FRSH_ERR_NOT_BOUND if endpoint is not bound to a valid vres \n
 462  *       FRSH_ERR_TOO_LARGE if the message is too large for the
 463  *                             network protocol \n
 464  *       FRSH_ERR_BUFFER_FULL if the message has been discarded
 465  *                            because the queue is full (and does not
 466  *                            have the policy FRSH_QP_OLDEST \n
 467  **/
 468 int frsh_send_async
 469   (const frsh_send_endpoint_t  endpoint,
 470    const void                  *msg,
 471    const size_t                size);
 472
 473 /**
 474  * frsh_send_sync()
 475  *
 476  * Similar to previous function but now the sending vres gets blocked
 477  * until the message is processed.
 478  **/
 479 int frsh_send_sync
 480   (const frsh_send_endpoint_t endpoint,
 481    void                       *msg,
 482    size_t                      size);
 483
 484 /**
 485  * frsh_send_endpoint_get_status()
 486  *
 487  * This function tells the number of messages still pending in the
 488  * endpoint queue, whether the network is up or down with some
 489  * optional information which is protocol_dependent.
 490  **/
 491 int frsh_send_endpoint_get_status
 492         (const frsh_send_endpoint_t endpoint,
 493          int *number_pending_msg,
 494          frsh_endpoint_network_status_t *network_status,
 495          frsh_protocol_status_t *protocol_status);
 496
 497 /**
 498  * frsh_receive_endpoint_create()
 499  *
 500  * This operation creates a receive endpoint associated with a
 501  * undirectional stream within a network interface of the node.
 502  *
 503  * Receiving endpoints are not bound to any network vres, this is
 504  * because don't originate any traffic.
 505  *
 506  * Note that the protocol address is not needed for reception because
 507  * it can be determined internally by FRSH based on the resource_id.
 508  *
 509  * Note also that messages may come from diferent originators.
 510  *
 511  * @param[in] resource_id  Id of the network from which we listen.
 512  * @param[in] stream_id  Id of the stream within the network.
 513  * @param[in] queueing_info Buffering information(queue size and
 514  *                          policy).
 515  * @param[in] protocol_info Extra protocol info opaque for the
 516  *                          application.
 517  * @param[in] endpoin  Placeholder for the endpoint object.
 518  *
 519  * @return 0 if successful \n
 520  *   FRSH_ERR_BAD_ARGUMENT if the stream or the network id are not
 521  *      valid \n
 522  **/
 523 int frsh_receive_endpoint_create
 524   (frsh_resource_id_t        resource_id,
 525    frsh_stream_id_t          stream_id,
 526    frsh_endpoint_queueing_info_t queueing_info,
 527    frsh_receive_endpoint_protocol_info_t protocol_info,
 528    frsh_receive_endpoint_t  *endpoint);
 529
 530 /**
 531  * frsh_receive_endpoint_get_params()
 532  *
 533  * This operation returns in the variables associated to the
 534  * endpoint at creation time.
 535  **/
 536 int frsh_receive_endpoint_get_params
 537      (const frsh_receive_endpoint_t  endpoint,
 538      frsh_resource_id_t        *resource_id,
 539      frsh_stream_id_t          *stream,
 540      frsh_endpoint_queueing_info_t   *queueing_info,
 541      frsh_receive_endpoint_protocol_info_t   *protocol_info);
 542
 543 /**
 544  * frsh_receive_endpoint_destroy()
 545  *
 546  * This operation eliminates any resources reserved for the referenced
 547  * endpoint.  Pending messages will be discarded and processor-vres
 548  * waiting in a synchronous operation will be awoken with an error
 549  * code.
 550  **/
 551 int frsh_receive_endpoint_destroy
 552      (frsh_receive_endpoint_t  endpoint);
 553
 554
 555 /**
 556  * frsh_receive_sync()
 557  *
 558  * If there are no messages available in the specified receive endpoint
 559  * this operation blocks the calling thread waiting for a message to be
 560  * received.
 561  *
 562  * When a message is available, if its size is less than or
 563  * equal to the buffer_size, the function stores it in the variable
 564  * pointed to by buffer and puts the number of bytes received in the
 565  * variable pointed to by message size.
 566  *
 567  * The function fails with FRSH_ERR_NO_SPACE if the buffersize is
 568  * too small for the message received.  In this case the message is
 569  * lost.
 570  *
 571  * Messages arriving at a destination buffer that is full will be
 572  * silently discarded (details in the queueing policy of the
 573  * endpoint). The application is responsible of reading the receive
 574  * endpoints with appropriate regularity, or of using a sequence
 575  * number or some other mechanism to detect any lost messages.
 576  *
 577  * @return 0 if successful \n
 578  *     FRSH_ERR_BAD_ARGUMENT if the endpoint is not valid, or if
 579  *       buffer or message_size are NULL.\n
 580  *     FRSH_ERR_NO_SPACE if the message size is bigger than the
 581  *       provided buffer \n
 582  **/
 583 int frsh_receive_sync
 584   (const frsh_receive_endpoint_t  endpoint,
 585    void                          *buffer,
 586    size_t                         buffer_size,
 587    size_t                        *message_size,
 588    frsh_network_address_t *from);
 589
 590 /**
 591  * frsh_receive_async()
 592  *
 593  * This operation is similar to the previous one but it works in a non
 594  * blocking (asynchronous) fashion.  If no message is available it
 595  * returns with error FRSH_NO_MESSAGE.
 596  *
 597  * @return 0 if successful \n
 598  *     FRSH_ERR_BAD_ARGUMENT if the endpoint is not valid, or if
 599  *       buffer or message_size are NULL \n
 600  *     FRSH_NO_MESSAGE if no messages are available in the queue \n
 601  *     FRSH_ERR_NO_SPACE if the message size is bigger than the
 602  *       provided buffer \n
 603  **/
 604 int frsh_receive_async
 605   (const frsh_receive_endpoint_t  endpoint,
 606    void                          *buffer,
 607    size_t                         buffer_size,
 608    size_t                        *message_size,
 609    frsh_network_address_t *from);
 610
 611
 612 /**
 613  * frsh_receive_endpoint_get_status
 614  *
 615  * This function tells the number of messages still pending in the
 616  * endpoint queue, whether the network is up or down and some optional
 617  * information which is protocol dependent.
 618  **/
 619 int frsh_receive_endpoint_get_status
 620         (const frsh_receive_endpoint_t endpoint,
 621          int *number_pending_messages,
 622          frsh_endpoint_network_status_t *network_status,
 623          frsh_protocol_status_t *protocol_status);
 624
 625 /*@}*/
 626
 627 #endif // _FRSH_DISTRIBUTED_H_