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_