frsh_distributed.h

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