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 #include "frsh_distributed_types.h"
  75 #include "frsh_core_types.h"
  76
  77 /**
  78  * @defgroup distributed Distributed module
  79  *
  80  * This module defines the functions and typedefs for use in
  81  * distributed applications.
  82  *
  83  * @{
  84  **/
  85
  86
  87
  88
  89 #define FRSH_DISTRIBUTED_MODULE_SUPPORTED       1
  90
  91
  92 //////////////////////////////////////////////////////////////////////
  93 //           TRANSMISSION SERVICES
  94 //////////////////////////////////////////////////////////////////////
  95
  96 /**
  97  * @defgroup txservices Transmission services
  98  * @ingroup distributed
  99  *
 100  * These functions need to be called before doing any FRSH operation
 101  * (including contract initialization).
 102  *
 103  * @{
 104  **/
 105
 106
 107 /**
 108  * frsh_send_endpoint_create()
 109  *
 110  * This operation creates a unidirectional input
 111  * data endpoint through which, after the
 112  * corresponding binding, it is possible to send
 113  * data.  network_id identifies the network to use,
 114  * receiver specifies the communication protocol
 115  * dependent information that is necessary to
 116  * address the receiving node, and port specifies
 117  * the communication protocol dependent information
 118  * that is necessary to get in contact with the
 119  * desired destination.
 120  * It returns 0 if
 121  * successful. It returns FRSH_ERR_BAD_ARGUMENT if
 122  * the endpoint is null, if the network_id is not
 123  * valid, or if the receiver or the port do not
 124  * conform to their expected formats.
 125  **/
 126 int frsh_send_endpoint_create
 127   (frsh_resource_id_t     network_id,
 128    frsh_node_address_t    receiver,
 129    frsh_port_t            port,
 130    frsh_send_endpoint_t  *endpoint);
 131
 132 /**
 133  * frsh_send_endpoint_destroy()
 134  *
 135  * This operation eliminates any resources reserved
 136  * for the referenced endpoint. If the endpoint is
 137  * bound to a network server, it is unbound from it
 138  * and can not be further used to invoke send
 139  * operations on it.
 140  * It returns 0 if successful,
 141  * or FRSH_ERR_BAD_ARGUMENT if the endpoint is not
 142  * valid.
 143  **/
 144 int frsh_send_endpoint_destroy
 145      (frsh_send_endpoint_t  *endpoint);
 146
 147 /**
 148  * frsh_send_endpoint_get_params()
 149  *
 150  * This operation returns (except for those NULL
 151  * arguments) in the variables pointed to by
 152  * network_id, receiver, or port, the corresponding
 153  * parameters used in the creation of the given
 154  * send endpoint.  It returns 0 if successful, or
 155  * FRSH_ERR_BAD_ARGUMENT if the endpoint is not
 156  * valid or all the other pointers are NULL.
 157  **/
 158 int frsh_send_endpoint_get_params
 159   (const frsh_send_endpoint_t  *endpoint,
 160    frsh_resource_id_t          *network_id,
 161    frsh_node_address_t         *receiver,
 162    frsh_port_t                 *port);
 163
 164 /**
 165  * frsh_endpoint_bind()
 166  *
 167  * This operation associates a send endpoint with a
 168  * server, which means that messages sent through
 169  * that endpoint will consume the server's reserved
 170  * bandwidth and its packets will be sent according
 171  * to the contract established for that server.  If
 172  * the endpoint is already bound to another server,
 173  * it is effectively unbound from it and bound to
 174  * the specified one.
 175  * The operation returns 0 if successful, or
 176  * FRSH_ERR_BAD_ARGUMENT if the endpoint or the server
 177  * are not valid, it also fails with a
 178  * value of FRSH_ERR_ALREADY_BOUND if the server is
 179  * already bound to some other send endpoint.
 180  * It fails with FRSH_ERR_WRONG_NETWORK if the server
 181  * network id is not the same as the one in the endpoint
 182  **/
 183 int frsh_endpoint_bind
 184   (frsh_vres_id_t      vres,
 185    frsh_send_endpoint_t  *endpoint);
 186
 187 /**
 188  * frsh_endpoint_unbind()
 189  *
 190  * This operation unbinds a send endpoint from a
 191  * server. Endpoints with no server associated
 192  * cannot be used to send data, and they stay in
 193  * that state  until they are either eliminated or
 194  * bound again.  The operation fails with
 195  * FRSH_ERR_NOT_BOUND if the endpoint has no server
 196  * bound
 197  **/
 198 int frsh_endpoint_unbind
 199   (frsh_send_endpoint_t  *endpoint);
 200
 201 /**
 202  * frsh_endpoint_get_vres_id()
 203  *
 204  * This operation copies the id of the server that
 205  * is bound to the specified send endpoint into the
 206  * variable pointed to by server.  It returns 0 if
 207  * successful, or FRSH_ERR_BAD_ARGUMENT if the
 208  * endpoint is not valid or server is NULL
 209  **/
 210 int frsh_endpoint_get_vres_id
 211   (const frsh_send_endpoint_t  *endpoint,
 212    frsh_vres_id_t            *server);
 213
 214 /**
 215  * frsh_send()
 216  *
 217  * This operation sends a message stored in msg and of length size
 218  * through the given endpoint. The operation is non-blocking and
 219  * returns immediately. An internal frsh service will schedule the
 220  * sending of messages and implement the communications sporadic server
 221  * corresponding to the network server bound to the given endpoint.
 222  * Messages sent through the same endpoint are received in the same
 223  * order in which they were sent It returns 0 if successful, but it
 224  * fails with FRSH_ERR_BAD_ARGUMENT if endpoint is not valid; it fails
 225  * with FRSH_ERR_NOT_BOUND is not bound to a valid server; it fails with
 226  * FRSH_ERR_TOO_LARGE if the message is too large for the network
 227  * protocol; it fails with FRSH_ERR_BUFFER_FULL if the sending queue is
 228  * full
 229  **/
 230 int frsh_send
 231   (const frsh_send_endpoint_t  *endpoint,
 232    void                       *msg,
 233    size_t                      size);
 234
 235 /**
 236  * frsh_receive_endpoint_create()
 237  *
 238  * This operation creates a receive endpoint with all the information
 239  * that is necessary to receive information from the specified network
 240  * and port It returns 0 if successful, but it fails with
 241  * FRSH_ERR_BAD_ARGUMENT if the port or the network id are not valid.
 242  **/
 243 int frsh_receive_endpoint_create
 244   (frsh_resource_id_t        network_id,
 245    frsh_port_t               port,
 246    frsh_receive_endpoint_t  *endpoint);
 247
 248 /**
 249  * frsh_receive_endpoint_destroy()
 250  *
 251  * This operation eliminates any resources reserved
 252  * for the referenced endpoint. it
 253  * can not be further used to invoke receive
 254  * operations on it.It returns 0 if successful, but it fails with
 255  * FRSH_ERR_BAD_ARGUMENT if endpoint is NULL or not valid.
 256  **/
 257 int frsh_receive_endpoint_destroy
 258      (frsh_receive_endpoint_t  *endpoint);
 259
 260 /**
 261  * frsh_receive_endpoint_get_parameters()
 262  *
 263  * This operation returns in the variables the_network_id,
 264  * and port, the corresponding
 265  * parameters used in the creation of the given
 266  * receive endpoint. It returns 0 if successful, but it fails with
 267  * FRSH_ERR_BAD_ARGUMENT if endpoint is NULL or not valid or network_id
 268  * or port are NULL
 269  **/
 270 int frsh_receive_endpoint_get_parameters
 271         (frsh_receive_endpoint_t  *endpoint,
 272          frsh_resource_id_t        *network_id,
 273          frsh_port_t              *the_port);
 274
 275 /**
 276  * frsh_receive()
 277  *
 278  * If there are no messages available in the specified receive endpoint
 279  * this operation blocks the calling thread waiting for a message to be
 280  * received. When a message is available, if its size is less than or
 281  * equal to the buffersize, the function stores it in the variable
 282  * pointed to by buffer and puts the number of bytes received in the
 283  * variable pointed to by messagesize.  The function fails with
 284  * FRSH_ERR_NO_SPACE if the buffersize is too small for the message
 285  * received (in which case the message is lost), or with
 286  * FRSH_ERR_BAD_ARGUMENT if the endpoint is not valid, or if buffer or
 287  * messagesize are NULL.  Messages arriving at a receiver buffer that
 288  * is full will be silently discarded. The application is responsible
 289  * of reading the receive endpoints with appropriate regularity, or of
 290  * using a sequence number or some other mechanism to detect any lost
 291  * messages.
 292  **/
 293 int frsh_receive
 294   (const frsh_receive_endpoint_t  *endpoint,
 295    void                          *buffer,
 296    size_t                         buffersize,
 297    size_t                        *messagesize);
 298
 299 /**
 300  * frsh_try_receive()
 301  *
 302  * This operation is the same as frsh_receive, except
 303  * that if there are no messages available in the
 304  * specified receive endpoint at the time of the call
 305  * the operation returns with an error of
 306  * FRSH_ERR_NO_MESSAGES
 307  **/
 308 int frsh_try_receive
 309   (const frsh_receive_endpoint_t  *endpoint,
 310    void                          *buffer,
 311    size_t                         buffersize,
 312    size_t                        *messagesize);
 313
 314 /*@}*/
 315
 316 //////////////////////////////////////////////////////////////////////
 317 //           GETTING CONFIGURATION INFORMATION
 318 //////////////////////////////////////////////////////////////////////
 319
 320 /**
 321  * @defgroup distgetconfig Getting Configuration Dependent Information
 322  * @ingroup distributed
 323  *
 324  * These functions provide information on parameters such as
 325  * transmission time and packet size.
 326  *
 327  * @{
 328  **/
 329
 330 /**
 331  * frsh_netconfig_set_packet_tx_time()
 332  *
 333  * This operation puts in the variable pointed to by budget
 334  * the transmission time that it takes to send a packet
 335  * through the network designated by network_id, when there
 336  * is no contention, but including any network overheads. It
 337  * is used to calculate the minimum and maximum budgets used
 338  * in the preparation of network contracts. The effective
 339  * network utilization budget (usually called bandwidth) is
 340  * always assiged as a number of packets per time unit, so
 341  * the time used in the negotiation of contracts will be
 342  * internally transformed into the corresponding necessary
 343  * number of packets. It returns FRSH_ERR_BAD_ARGUMENT if
 344  * network_id is not a valid identifier or if budget is a
 345  * NULL pointer.
 346  **/
 347 int frsh_netconfig_set_packet_tx_time
 348   (frsh_resource_id_t      network_id,
 349    struct timespec       *budget);
 350
 351 /**
 352  * frsh_netconfig_set_packet_size()
 353  *
 354  * This operation puts in the variable pointed to by
 355  * packet_size the maximum number of bytes that can be sent
 356  * in a packet through the network designated by network_id.
 357  * It is usually a configuration value and it helps the user
 358  * application to calculate the number of packets it will
 359  * need to reserve for the periodic transmision of its
 360  * messages and consequently prepare the corresponding
 361  * contracts. It returns FRSH_ERR_BAD_ARGUMENT if network_id
 362  * is not a valid identifier or if packet_size is a NULL
 363  * pointer.
 364  **/
 365 int frsh_netconfig_set_packet_size
 366   (frsh_resource_id_t      network_id,
 367    size_t               *packet_size);
 368
 369 /**
 370  * frsh_netconfig_set_max_message_size()
 371  *
 372  * This operation is used to obtain the maximum number of
 373  * packets of which a message can be formed, for the
 374  * specified network. A message is defined as the piece of
 375  * information used in a send operation. Since the value
 376  * returned by this operation is measured in packet units,
 377  * the effective size can be calculated multiplying this
 378  * value by the size of a packet.  When the value returned by
 379  * this operation is larger than 1 it means the
 380  * implementation will make the partition of messages into
 381  * packets and its recomposition at the receiving node. It
 382  * returns FRSH_ERR_BAD_ARGUMENT if network_id is not a valid
 383  * identifier or the pointer max_msg_size is NULL
 384  **/
 385 int frsh_netconfig_set_max_message_size
 386   (frsh_resource_id_t      network_id,
 387    size_t                *max_msg_size);
 388 /*@}*/
 389
 390
 391 #endif // _FRSH_DISTRIBUTED_H_