Subversion Repositories shark

/**
   @file Distributed.
 */

//fsf_distributed.h
//=====================================================================
//       FFFFFFIII   RRRRR      SSTTTTTTT
//      FF         IIR   RR    SS
//     FF           IR        SS
//    FFFFFF         RRRR    SSSSST
//   FF       FI       RRR  SS
//  FF         II     RRR  SS
// FF           IIIIIR    RS
//
// FSF(FIRST Scheduling Framework)
// distributed services functionality
//=====================================================================

#include "fsf_core.h"

#ifndef _FSF_DISTRIBUTED_H_
#define _FSF_DISTRIBUTED_H_

#define FSF_DISTRIBUTED_MODULE_SUPPORTED       1


/**

   \ingroup distjmodule

   This operation identifies a contract as a bandwidth reservation on
   the network identified by the network input parameter. Then the
   contract negotiation is performed using the conventional
   negotiation functions, including the possibility of grouping the
   contract with others. If the network_id given is
   FSF_NULL_NETWORK_ID, the contract is considered not to reserve
   bandwidth in a network but to operate as any other regular
   contract. It returns 0 if successful, or FSF_ERR_BAD_ARGUMENT if
   contract is null or the network id is not valid.
*/
int
fsf_set_contract_network_id
  (fsf_contract_parameters_t *contract,
   fsf_network_id_t           network_id);

/**

   \ingroup distjmodule

   This operation puts the network identification corresponding to the
   contract parameters object pointed to by contract in the variable
   pointed to by network_id. If the contract is a regular one and
   therefore has not a network_id set, it puts the FSF_NULL_NETWORK_ID
   constant instead.  it returns 0 if successful, or
   FSF_ERR_BAD_ARGUMENT if any of the pointers is null.
*/
int
fsf_get_contract_network_id
  (const fsf_contract_parameters_t *contract,
   fsf_network_id_t                *network_id);

//Transmission services:

//opaque types for fsf endpoints
typedef FSF_SEND_ENDPOINT_T_OPAQUE   fsf_send_endpoint_t;
typedef FSF_RECEIVE_ENDPOINT_T_OPAQUE fsf_receive_endpoint_t;

/**
   \ingroup distjmodule

   The node_address type specifies the node address in a
   communication-protocol-independent way. The actual address is
   obtained via a configuration dependent mapping function
*/
typedef unsigned int  fsf_node_address_t;

/**
   \ingroup distjmodule

   The port type specifies the information that is necessary to get in
   contact with the thread in the receiving node, in a
   protocol-independent way.  The actual port number is obtained via a
   configuration dependent mapping function
*/
typedef unsigned int  fsf_port_t;

/**

   \ingroup distjmodule

   This operation creates a unidirectional input data endpoint through
   which, after the corresponding binding, it is possible to send
   data.  network_id identifies the network to use, receiver specifies
   the communication protocol dependent information that is necessary
   to address the receiving node, and port specifies the communication
   protocol dependent information that is necessary to get in contact
   with the desired destination.  It returns 0 if successful. It
   returns FSF_ERR_BAD_ARGUMENT if the endpoint is null, if the
   network_id is not valid, or if the receiver or the port do not
   conform to their expected formats.
*/
int
fsf_create_send_endpoint
  (fsf_network_id_t      network_id,
   fsf_node_address_t    receiver,
   fsf_port_t            port,
   fsf_send_endpoint_t  *endpoint);

/**
   \ingroup distjmodule

   This operation eliminates any resources reserved for the referenced
   endpoint. If the endpoint is bound to a network server, it is
   unbound from it and can not be further used to invoke send
   operations on it.  It returns 0 if successful, or
   FSF_ERR_BAD_ARGUMENT if the endpoint is not valid.
*/
int
fsf_destroy_send_endpoint
  (fsf_send_endpoint_t  *endpoint);

/**
   \ingroup distjmodule

   This operation returns (except for those NULL arguments) in the
   variables pointed to by network_id, receiver, or port, the
   corresponding parameters used in the creation of the given send
   endpoint.  It returns 0 if successful, or FSF_ERR_BAD_ARGUMENT if
   the endpoint is not valid.
*/
int
fsf_get_send_endpoint_parameters
  (const fsf_send_endpoint_t  *endpoint,
   fsf_network_id_t           *network_id,
   fsf_node_address_t         *receiver,
   fsf_port_t                 *port);

/**
   \ingroup distjmodule

   This operation associates a send endpoint with a server, which
   means that messages sent through that endpoint will consume the
   server's reserved bandwidth and its packets will be sent according
   to the contract established for that server.  If the endpoint is
   already bound to another server, it is effectively unbound from it
   and bound to the specified one.  The operation returns 0 if
   successful, or FSF_ERR_BAD_ARGUMENT if the endpoint or the server
   are not valid, it also fails with a value of FSF_ERR_ALREADY_BOUND
   if the server is already bound to some other send endpoint.  It
   fails with FSF_ERR_WRONG_NETWORK if the server network id is not
   the same as the one in the endpoint */
int
fsf_bind_endpoint_to_server
  (fsf_server_id_t server,
   fsf_send_endpoint_t *endpoint);

/**
   \ingroup distjmodule

   This operation unbinds a send endpoint from a server Endpoints with
   no server associated cannot be used to send data, and they stay in
   that state until they are either eliminated or bound again.  The
   operation fails with FSF_ERR_NOT_BOUND if the endpoint has no
   server bound */
int
fsf_unbind_endpoint_from_server
  (fsf_send_endpoint_t  *endpoint);

/**
   \ingroup distjmodule

   This operation copies the id of the server that
   is bound to the specified send endpoint into the
   variable pointed to by server.  It returns 0 if
   successful, or FSF_ERR_BAD_ARGUMENT if the
   endpoint is not valid or server is NULL
*/
int
fsf_get_endpoint_server
  (const fsf_send_endpoint_t  *endpoint,
   fsf_server_id_t            *server);


/**
   \ingroup distjmodule

   This operation sends a message stored in msg and of length size
   through the given endpoint. The operation is non-blocking and
   returns immediately. An internal fsf service will schedule the
   sending of messages and implement the communications sporadic
   server corresponding to the network server bound to the given
   endpoint.  Messages sent through the same endpoint are received in
   the same order in which they were sent It returns 0 if successful,
   but it fails with FSF_ERR_BAD_ARGUMENT if endpoint is not valid; it
   fails with FSF_ERR_NOT_BOUND is not bound to a valid server; it
   fails with FSF_ERR_TOO_LARGE if the message is too large for the
   network protocol; it fails with FSF_ERR_BUFFER_FULL if the sending
   queue is full */
int
fsf_send
  (const fsf_send_endpoint_t  *endpoint,
   void                       *msg,
   size_t                      size);

/**
   \ingroup distjmodule

   This operation creates a receive endpoint with all the information
   that is necessary to receive information from the specified network
   and port It returns 0 if successful, but it fails with
   FSF_ERR_BAD_ARGUMENT if the port or the network id are not
   valid. */
int
fsf_create_receive_endpoint
  (fsf_network_id_t         network_id,
   fsf_port_t               port,
   fsf_receive_endpoint_t  *endpoint);

/**
   \ingroup distjmodule

   If there are no messages available in the specified receive
   endpoint this operation blocks the calling thread waiting for a
   message to be received. When a message is available, if its size is
   less than or equal to the buffersize, the function stores it in the
   variable pointed to by buffer and puts the number of bytes received
   in the variable pointed to by messagesize.  The function fails with
   FSF_ERR_NO_SPACE if the buffersize is too small for the message
   received (in which case the message is lost), or with
   FSF_ERR_BAD_ARGUMENT if the endpoint is not valid, or if buffer or
   messagesize are NULL.  Messages arriving at a receiver buffer that
   is full will be silently discarded. The application is responsible
   of reading the receive endpoints with appropriate regularity, or of
   using a sequence number or some other mechanism to detect any lost
   messages.*/
int
fsf_receive
  (const fsf_receive_endpoint_t  *endpoint,
   void                          *buffer,
   size_t                         buffersize,
   size_t                        *messagesize);

/**
   \ingroup distjmodule

   This operation is the same as fsf_receive, except that if there are
   no messages available in the specified receive endpoint at the time
   of the call the operation returns with an error of
   FSF_ERR_NO_MESSAGES */
int
fsf_try_receive
  (const fsf_receive_endpoint_t  *endpoint,
   void                          *buffer,
   size_t                         buffersize,
   size_t                        *messagesize);

/**
   \ingroup distjmodule

   This operation is used to calculate the minimum and/or maximum
   budgets used in the preparation of network contracts. It puts in
   the variable pointed to by budget the transmission time that it
   takes to send a message of size msg_size through the network
   designated by network_id, when there is no contention, but
   including any network overheads It returns FSF_ERR_BAD_ARGUMENT if
   network_id is not a valid identifier or if budget is a NULL
   pointer.*/
int
fsf_tx_time
  (fsf_network_id_t      network_id,
   size_t                msg_size,
   struct timespec       *budget);

/**
   \ingroup distjmodule

   This operation is used to obtain the maximum message size for the
   specified network It returns FSF_ERR_BAD_ARGUMENT if network_id is
   not a valid identifier or if max_msg_size is NULL */
int
fsf_max_message_size
  (fsf_network_id_t      network_id,
   size_t                *max_msg_size);


#endif // _FSF_DISTRIBUTED_H_