Subversion Repositories shark

//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


//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);


//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;

//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;

//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;

//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);

//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);

//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);

//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);

//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);

//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);

//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);

//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);

//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);

//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);

//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);

//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_