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_