From: telleriam Date: Thu, 15 Feb 2007 18:42:41 +0000 (+0000) Subject: Adding new distributed systems X-Git-Url: https://rtime.felk.cvut.cz/gitweb/frescor/frsh-include.git/commitdiff_plain/a4a76a12390f1bc4c4d8f52abb4c3772b4f14e47 Adding new distributed systems git-svn-id: http://www.frescor.org/private/svn/frescor/frsh/trunk/include@298 35b4ef3e-fd22-0410-ab77-dab3279adceb --- diff --git a/frsh_adaption.h b/frsh_adaption.h index fd7eae5..1dd6edd 100644 --- a/frsh_adaption.h +++ b/frsh_adaption.h @@ -1,12 +1,49 @@ -/* -** frsh_adaption.h -** -** Made by Miguel marciano -** Login -** -** Started on Mon Feb 12 17:20:19 2007 Miguel marciano -** Last update Mon Feb 12 17:20:19 2007 Miguel marciano -*/ +// ----------------------------------------------------------------------- +// Copyright (C) 2005 Mälardalen University, SWEDEN +// Scuola Superiore S.Anna, ITALY +// Universidad de Cantabria, SPAIN +// University of York, UK +// +// FRSH API web pages: http://marte.unican.es/frsh/docs/ +// http://shark.sssup.it/contrib/first/docs/ +// +// This file is part of FRSH API +// +// FRSH API is free software; you can redistribute it and/or modify +// it under the terms of the GNU General Public License as published by +// the Free Software Foundation; either version 2, or (at your option) +// any later version. +// +// FRSH API is distributed in the hope that it will be useful, but +// WITHOUT ANY WARRANTY; without even the implied warranty of +// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +// General Public License for more details. +// +// You should have received a copy of the GNU General Public License +// distributed with FRSH API; see file COPYING. If not, write to the +// Free Software Foundation, 59 Temple Place - Suite 330, Boston, MA +// 02111-1307, USA. +// +// As a special exception, if you include this header file into source +// files to be compiled, this header file does not by itself cause +// the resulting executable to be covered by the GNU General Public +// License. This exception does not however invalidate any other +// reasons why the executable file might be covered by the GNU General +// Public License. +// ----------------------------------------------------------------------- +// frsh_adaption.h +//============================================== +// ******** ******* ******** ** ** +// **///// /**////** **////// /** /** +// ** /** /** /** /** /** +// ******* /******* /********* /********** +// **//// /**///** ////////** /**//////** +// ** /** //** /** /** /** +// ** /** //** ******** /** /** +// // // // //////// // // +// +// FRSH(FRescor ScHeduler), pronounced "fresh" +//============================================== #ifndef FRSH_ADAPTION_H_ #define FRSH_ADAPTION_H_ diff --git a/frsh_distributed.h b/frsh_distributed.h index 2c2bfd9..2511c55 100644 --- a/frsh_distributed.h +++ b/frsh_distributed.h @@ -80,13 +80,151 @@ * This module defines the functions and typedefs for use in * distributed applications. * + * Each network is identified by its network_id and FRSH hides its + * characteristics completely. The type of network is implied with + * its ID via a configuration table defined at compile time. + * + * This are the typical steps performed to exchange messages in a + * distributed system. + * + * 1. Map (internally in FRSH implementation) + * - node--> node_addresses + * - network --> network_id's + * - unidirectional communication channel --> stream_id + * - other config --> protocol_info. + * + * 2. One of the nodes (which one is protocol-dependent) negotiates a + * "network contract" per communication channel that is used in + * the application. In each contract it is specified: + * - frsh_resource_type = FRSH_RT_NETWORK. + * - frsh_resource_id = + * - budget: Time needed to send the require data per period. + * (you can use frsh_netinfo_*() functions for this). + * - period: Period of sendings. + * - Other protocol dependent function in protocol_contract_info. + * + * 2. In a sending node: + * 2.1. Create a send_endpoint per any unidirectional stream that will + * be used in sending + * network_id --> the network through which the stream will + * flow (this is extra info needed for coherency + * with the bind). + * destinator --> node_address of the receiver. + * stream_id --> the unidirectional communication channel. + * 2.2. Bind the send_endpoint to the network contract negotiated + * above. + * 2.3. The (processor) sending vres invokes frsh_send_(a)sync() to + * send the data through the corresponding stream. + * + * 3. In a receiving node: + * 3.1. Create a receive_endpoint per any unidirectional stream + * that will be used in receiving. + * 3.2. The processor expecting a reception of message invokes + * frsh_receive_(a)sync() to read the incoming data. + * + * 4. When all comunication is finished and the channel is no longer + * needed the nodes will destroy the send and receive endpoints + * and the network contract will be canceled. + **/ + +#define FRSH_DISTRIBUTED_MODULE_SUPPORTED 1 + +////////////////////////////////////////////////////////////////////// +// CONTRACT ASPECTS +////////////////////////////////////////////////////////////////////// + +/** + * @defgroup distcontract Contract Info for Distributed Systems + * @ingroup distributed + * + * These functions help you calculate the needed budget for network + * contracts and also to include protocol dependent info in contract + * parameters. + * * @{ **/ +/** + * frsh_netinfo_get_packet_tx_time() + * + * This operation gives the transmission time that it takes to send a + * packet of the maximum size through the network designated by + * network_id, when there is no contention, but including any network + * overheads. + * + * It must be used by the application to calculate the minimum and + * maximum budgets used in the preparation of network contracts. + * + * The effective network utilization budget (usually called bandwidth) + * is always assigned as a number of packets per time unit, so the + * time used in the negotiation of contracts will be internally + * transformed into the corresponding necessary number of packets. + * + * It returns FRSH_ERR_BAD_ARGUMENT if network_id is not a valid + * identifier or if budget is a NULL pointer. + **/ +int frsh_netinfo_get_packet_tx_time + (frsh_resource_id_t network_id, + struct timespec *budget); + +/** + * frsh_netconfig_get_packet_size() + * + * This operation gives the maximum number of bytes that can be sent + * in a packet (MTU) through the network designated by network_id. + * + * It is usually a configuration value and it helps the user + * application to calculate the number of packets it will need to + * reserve for the periodic transmision of its messages and consequently + * prepare the corresponding contracts. + * + * It returns FRSH_ERR_BAD_ARGUMENT if network_id is not a valid + * identifier or if packet_size is a NULL pointer. + **/ +int frsh_netinfo_get_max_packet_size + (frsh_resource_id_t network_id, + size_t *packet_size); + +/** + * frsh_netconfig_get_max_packet_in_msg() + * + * This operation is used to obtain the maximum number of packets of + * which a message can be formed, for the specified network. + * + * A message is defined as the piece of information used in a send + * operation. Since the value returned by this operation is measured + * in packet units, the effective size can be calculated multiplying + * this value by the size of a packet. + * + * When the value returned by this operation is larger than 1 it means + * the implementation will make the partition of messages into packets + * and its recomposition at the receiving node. + * + * It returns FRSH_ERR_BAD_ARGUMENT if network_id is not a valid + * identifier or the pointer max_msg_size is NULL. + **/ +int frsh_netinfo_get_max_packet_in_msg + (frsh_resource_id_t network_id, + size_t *max_msg_size); + +/** + * frsh_contract_set_protocol_info + * + * We add protocol info to the contract + **/ +int frsh_contract_set_protocol_info(frsh_protocol_info_t protocol_info, + frsh_contract_t *contract); +/** + * frsh_contract_get_protocol_info + * + * We get protocol info from the contract + **/ +int frsh_contract_get_protocol_info(frsh_contract_t contract, + frsh_protocol_info_t *protocol_info); +/*@}*/ -#define FRSH_DISTRIBUTED_MODULE_SUPPORTED 1 ////////////////////////////////////////////////////////////////////// @@ -97,9 +235,10 @@ * @defgroup txservices Transmission services * @ingroup distributed * - * These functions need to be called before doing any FRSH operation - * (including contract initialization). - * + * These functions allow to create and manage endpoints for sending + * and receiving and to perform send and receive operations both + * synchronously (blocking) and asynchronously (non-blocking). + * * @{ **/ @@ -107,105 +246,109 @@ /** * frsh_send_endpoint_create() * - * 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 FRSH_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. + * This operation creates a unidirectional stream input endpoint + * through which, after the corresponding binding, it is possible to + * send data to a unicast or multicast receiver. + * + * @param[in] network_id Identifier of the network referred in the + * network contract as a resource_id. + * @param[in] receiver FRSH abstraction of the protocol address for the + * destinator node. + * @param[in] stream_id Identifier of the communication channel between + * the nodes. Multiplexing is achieved by using + * different streams between the same nodes and the + * same network. + * @param[in] queueing_info Queueing params of the endpoint (size and + * policy). + * @param[in] protocol_info Optional protocol-dependent info. + * @param[out] endpoint Placeholder for the endpoint object. **/ int frsh_send_endpoint_create (frsh_resource_id_t network_id, frsh_node_address_t receiver, - frsh_port_t port, + frsh_stream_id_t stream_id, + frsh_endpoint_queueing_info_t queueing_info, + frsh_protocol_info_t protocol_info, frsh_send_endpoint_t *endpoint); /** - * frsh_send_endpoint_destroy() + * frsh_send_endpoint_get_params() * - * This operation eliminates any resources reserved - * for the referenced endpoint. If the endpoint is - * bound to a network vres, it is unbound from it - * and can not be further used to invoke send - * operations on it. - * It returns 0 if successful, - * or FRSH_ERR_BAD_ARGUMENT if the endpoint is not - * valid. + * This operation returns in the variables associated to the + * endpoint at creation time. **/ -int frsh_send_endpoint_destroy - (frsh_send_endpoint_t *endpoint); +int frsh_send_endpoint_get_params + (const frsh_send_endpoint_t *endpoint, + frsh_resource_id_t *network_id, + frsh_node_address_t *receiver, + frsh_stream_id_t *stream, + frsh_endpoint_queueing_info_t *queueing_info, + frsh_protocol_info_t *protocol_info +); /** - * frsh_send_endpoint_get_params() + * frsh_send_endpoint_destroy() * - * 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 - * FRSH_ERR_BAD_ARGUMENT if the endpoint is not - * valid or all the other pointers are NULL. + * This operation eliminates any resources reserved for the referenced + * endpoint. Pending messages will be discarded and processor-vres + * waiting in a synchronous operation will be awoken with an error + * code. **/ -int frsh_send_endpoint_get_params - (const frsh_send_endpoint_t *endpoint, - frsh_resource_id_t *network_id, - frsh_node_address_t *receiver, - frsh_port_t *port); +int frsh_send_endpoint_destroy + (frsh_send_endpoint_t *endpoint); + /** - * frsh_endpoint_bind() - * - * This operation associates a send endpoint with a - * vres, which means that messages sent through - * that endpoint will consume the vres's reserved - * bandwidth and its packets will be sent according - * to the contract established for that vres. If - * the endpoint is already bound to another vres, - * it is effectively unbound from it and bound to - * the specified one. - * The operation returns 0 if successful, or - * FRSH_ERR_BAD_ARGUMENT if the endpoint or the vres - * are not valid, it also fails with a - * value of FRSH_ERR_ALREADY_BOUND if the vres is - * already bound to some other send endpoint. - * It fails with FRSH_ERR_WRONG_NETWORK if the vres - * network id is not the same as the one in the endpoint + * frsh_send_endpoint_bind() + * + * This operation associates a send endpoint with a network vres, + * which means that messages sent through this endpoint will consume + * the vres's reserved bandwidth and its packets will be sent + * according to the contract established for that vres. + * + * If the endpoint is already bound to another vres, it is effectively + * unbound from it and bound to the specified one. However if a vres + * is already bound to another endpoint an error is returned. + * + * A consistency check is done in which the network_id specified at + * endpoint creation must correspond to the resource_id of the vres + * contract. + * + * @return 0 if successful + * FRSH_ERR_BAD_ARGUMENT if the endpoint or the vres are not + * valid + * FRSH_ERR_ALREADY_BOUND if the vres is already bound to some + * other send endpoint. + * FRSH_ERR_WRONG_NETWORK if the vres network id is not the same + * as the one in the endpoint **/ -int frsh_endpoint_bind +int frsh_send_endpoint_bind (frsh_vres_id_t vres, frsh_send_endpoint_t *endpoint); /** - * frsh_endpoint_unbind() - * - * This operation unbinds a send endpoint from a - * vres. Endpoints with no vres 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 - * FRSH_ERR_NOT_BOUND if the endpoint has no vres - * bound + * frsh_send_endpoint_unbind() + * + * This operation unbinds a send endpoint from a vres. Endpoints with + * no vres associated cannot be used to send data, and they stay in + * that state until they are either eliminated or bound again. + * + * @return 0 if successful + * FRSH_ERR_NOT_BOUND if the endpoint was not bound. **/ -int frsh_endpoint_unbind +int frsh_send_endpoint_unbind (frsh_send_endpoint_t *endpoint); /** * frsh_endpoint_get_vres_id() * - * This operation copies the id of the vres that - * is bound to the specified send endpoint into the - * variable pointed to by vres. It returns 0 if - * successful, or FRSH_ERR_BAD_ARGUMENT if the - * endpoint is not valid or vres is NULL + * This operation copies the id of the vres that is bound to the + * specified send endpoint into the variable pointed to by vres. + * + * @return 0 if successful + * FRSH_ERR_NOT_BOUND if the endpoint was not bound. + * FRSH_ERR_BAD_ARGUMENT if the endpoint is not valid or vres + * is NULL **/ int frsh_endpoint_get_vres_id (const frsh_send_endpoint_t *endpoint, @@ -216,175 +359,179 @@ int frsh_endpoint_get_vres_id * * 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 frsh service will schedule the - * sending of messages and implement the communications sporadic vres - * corresponding to the network vres bound to the given endpoint. + * returns immediately. + * + * An internal frsh service will schedule the sending of messages and + * implement the communications sporadic vres corresponding to the + * network vres 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 FRSH_ERR_BAD_ARGUMENT if endpoint is not valid; it fails - * with FRSH_ERR_NOT_BOUND is not bound to a valid vres; it fails with - * FRSH_ERR_TOO_LARGE if the message is too large for the network - * protocol; it fails with FRSH_ERR_BUFFER_FULL if the sending queue is - * full + * order in which they were sent. + * + * @returns 0 if successful + * FRSH_ERR_BAD_ARGUMENT if endpoint is not valid + * FRSH_ERR_NOT_BOUND if endpoint is not bound to a valid vres + * FRSH_ERR_TOO_LARGE if the message is too large for the + * network protocol + * FRSH_ERR_BUFFER_FULL if the message has been discarded + * because the queue is full (and does not + * have the policy FRSH_QP_OLDEST. **/ int frsh_send (const frsh_send_endpoint_t *endpoint, void *msg, size_t size); +/** + * frsh_send_sync() + * + * Similar to previous function but now the sending vres gets blocked + * until the message is processed. + **/ +int frsh_send_sync + (const frsh_send_endpoint_t *endpoint, + void *msg, + size_t size); + + + +/** + * frsh_send_endpoint_get_status() + * + * This function tells the number of messages still pending in the + * endpoint queue together with some optional information which is + * protocol_dependent. + **/ +int frsh_send_endpoint_get_status(const frsh_send_endpoint_t *endpoint, + int *number_pending_msg, + frsh_protocol_info_t *protocol_info); + /** * frsh_receive_endpoint_create() * - * 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 - * FRSH_ERR_BAD_ARGUMENT if the port or the network id are not valid. + * This operation creates a receive endpoint associated with a + * undirectional stream within a network interface of the node. + * + * Receiving endpoints are not bound to any network vres, this is + * because don't originate any traffic. + * + * Note that the protocol address is not needed for reception because + * it can be determined internally by FRSH based on the network_id. + * + * Note also that messages may come from diferent originators. + * + * @param[in] network_id Id of the network from which we listen. + * @param[in] stream_id Id of the stream within the network. + * @param[in] queueing_info Buffering information(queue size and + * policy). + * @param[in] protocol_info Extra protocol info opaque for the + * application. + * @param[in] endpoin Placeholder for the endpoint object. + * + * @return 0 if successful + * FRSH_ERR_BAD_ARGUMENT if the stream or the network id are not valid. **/ int frsh_receive_endpoint_create (frsh_resource_id_t network_id, - frsh_port_t port, + frsh_stream_id_t stream_id, + frsh_endpoint_queueing_info_t queueing_info, + frsh_protocol_info_t protocol_info, frsh_receive_endpoint_t *endpoint); + +/** + * frsh_receive_endpoint_get_params() + * + * This operation returns in the variables associated to the + * endpoint at creation time. + **/ +int frsh_receive_endpoint_get_params + (frsh_resource_id_t *network_id, + frsh_stream_id_t *stream, + frsh_endpoint_queueing_info_t *queueing_info, + frsh_protocol_info_t *protocol_info, + const frsh_receive_endpoint_t *endpoint); + /** * frsh_receive_endpoint_destroy() * - * This operation eliminates any resources reserved - * for the referenced endpoint. it - * can not be further used to invoke receive - * operations on it.It returns 0 if successful, but it fails with - * FRSH_ERR_BAD_ARGUMENT if endpoint is NULL or not valid. + * This operation eliminates any resources reserved for the referenced + * endpoint. Pending messages will be discarded and processor-vres + * waiting in a synchronous operation will be awoken with an error + * code. **/ int frsh_receive_endpoint_destroy (frsh_receive_endpoint_t *endpoint); -/** - * frsh_receive_endpoint_get_parameters() - * - * This operation returns in the variables the_network_id, - * and port, the corresponding - * parameters used in the creation of the given - * receive endpoint. It returns 0 if successful, but it fails with - * FRSH_ERR_BAD_ARGUMENT if endpoint is NULL or not valid or network_id - * or port are NULL - **/ -int frsh_receive_endpoint_get_parameters - (frsh_receive_endpoint_t *endpoint, - frsh_resource_id_t *network_id, - frsh_port_t *the_port); /** - * frsh_receive() + * frsh_receive_sync() * * 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 + * received. + * + * When a message is available, if its size is less than or + * equal to the buffer_size, 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 - * FRSH_ERR_NO_SPACE if the buffersize is too small for the message - * received (in which case the message is lost), or with - * FRSH_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. + * variable pointed to by message size. + * + * The function fails with FRSH_ERR_NO_SPACE if the buffersize is + * too small for the message received. In this case the message is + * lost. + * + * Messages arriving at a receiver buffer that is full will be + * silently discarded (details in the queueing policy of the + * endpoint). 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. + * + * @return 0 if successful + * FRSH_ERR_BAD_ARGUMENT if the endpoint is not valid, or if + * buffer or message_size are NULL. + * FRSH_ERR_NO_SPACE if the message size is bigger than the + * provided buffer. **/ -int frsh_receive +int frsh_receive_sync (const frsh_receive_endpoint_t *endpoint, void *buffer, - size_t buffersize, - size_t *messagesize); + size_t buffer_size, + size_t *message_size); /** - * frsh_try_receive() + * frsh_receive() * - * This operation is the same as frsh_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 - * FRSH_ERR_NO_MESSAGES + * This operation is similar to the previous one but it works in a non + * blocking (asynchronous) fashion. If no message is available it + * returns with error FRSH_NO_MESSAGE. + * + * @return 0 if successful + * FRSH_ERR_BAD_ARGUMENT if the endpoint is not valid, or if + * buffer or message_size are NULL. + * FRSH_NO_MESSAGE if no messages are available in the queue. + * FRSH_ERR_NO_SPACE if the message size is bigger than the + * provided buffer. **/ -int frsh_try_receive +int frsh_receive (const frsh_receive_endpoint_t *endpoint, void *buffer, - size_t buffersize, - size_t *messagesize); + size_t buffer_size, + size_t *message_size); -/*@}*/ - -////////////////////////////////////////////////////////////////////// -// GETTING CONFIGURATION INFORMATION -////////////////////////////////////////////////////////////////////// /** - * @defgroup distgetconfig Getting Configuration Dependent Information - * @ingroup distributed - * - * These functions provide information on parameters such as - * transmission time and packet size. + * frsh_receive_endpoint_get_status * - * @{ + * This function tells the number of messages still pending in the + * endpoint queue together with some optional information which is + * protocol_dependent. **/ +int frsh_send_endpoint_get_status(const frsh_receive_endpoint_t *endpoint, + int *number_pending_messages, + frsh_protocol_info_t *protocol_info); -/** - * frsh_netconfig_set_packet_tx_time() - * - * This operation puts in the variable pointed to by budget - * the transmission time that it takes to send a packet - * through the network designated by network_id, when there - * is no contention, but including any network overheads. It - * is used to calculate the minimum and maximum budgets used - * in the preparation of network contracts. The effective - * network utilization budget (usually called bandwidth) is - * always assiged as a number of packets per time unit, so - * the time used in the negotiation of contracts will be - * internally transformed into the corresponding necessary - * number of packets. It returns FRSH_ERR_BAD_ARGUMENT if - * network_id is not a valid identifier or if budget is a - * NULL pointer. - **/ -int frsh_netconfig_set_packet_tx_time - (frsh_resource_id_t network_id, - struct timespec *budget); -/** - * frsh_netconfig_set_packet_size() - * - * This operation puts in the variable pointed to by - * packet_size the maximum number of bytes that can be sent - * in a packet through the network designated by network_id. - * It is usually a configuration value and it helps the user - * application to calculate the number of packets it will - * need to reserve for the periodic transmision of its - * messages and consequently prepare the corresponding - * contracts. It returns FRSH_ERR_BAD_ARGUMENT if network_id - * is not a valid identifier or if packet_size is a NULL - * pointer. - **/ -int frsh_netconfig_set_packet_size - (frsh_resource_id_t network_id, - size_t *packet_size); -/** - * frsh_netconfig_set_max_message_size() - * - * This operation is used to obtain the maximum number of - * packets of which a message can be formed, for the - * specified network. A message is defined as the piece of - * information used in a send operation. Since the value - * returned by this operation is measured in packet units, - * the effective size can be calculated multiplying this - * value by the size of a packet. When the value returned by - * this operation is larger than 1 it means the - * implementation will make the partition of messages into - * packets and its recomposition at the receiving node. It - * returns FRSH_ERR_BAD_ARGUMENT if network_id is not a valid - * identifier or the pointer max_msg_size is NULL - **/ -int frsh_netconfig_set_max_message_size - (frsh_resource_id_t network_id, - size_t *max_msg_size); /*@}*/ diff --git a/frsh_distributed_spare_capacity.h b/frsh_distributed_spare_capacity.h deleted file mode 100644 index bf3886a..0000000 --- a/frsh_distributed_spare_capacity.h +++ /dev/null @@ -1,144 +0,0 @@ -// ----------------------------------------------------------------------- -// Copyright (C) 2006 - 2007 FRESCOR consortium partners: -// -// Universidad de Cantabria, SPAIN -// University of York, UK -// Scuola Superiore Sant'Anna, ITALY -// Kaiserslautern University, GERMANY -// Univ. Politécnica Valencia, SPAIN -// Czech Technical University in Prague, CZECH REPUBLIC -// ENEA SWEDEN -// Thales Communication S.A. FRANCE -// Visual Tools S.A. SPAIN -// Rapita Systems Ltd UK -// Evidence ITALY -// -// See http://www.frescor.org for a link to partners' websites -// -// FRESCOR project (FP6/2005/IST/5-034026) is funded -// in part by the European Union Sixth Framework Programme -// The European Union is not liable of any use that may be -// made of this code. -// -// -// based on previous work (FSF) done in the FIRST project -// -// Copyright (C) 2005 Mälardalen University, SWEDEN -// Scuola Superiore S.Anna, ITALY -// Universidad de Cantabria, SPAIN -// University of York, UK -// -// FSF API web pages: http://marte.unican.es/fsf/docs -// http://shark.sssup.it/contrib/first/docs/ -// -// This file is part of FRSH API -// -// FRSH API is free software; you can redistribute it and/or modify -// it under the terms of the GNU General Public License as published by -// the Free Software Foundation; either version 2, or (at your option) -// any later version. -// -// FRSH API is distributed in the hope that it will be useful, but -// WITHOUT ANY WARRANTY; without even the implied warranty of -// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -// General Public License for more details. -// -// You should have received a copy of the GNU General Public License -// distributed with FRSH API; see file COPYING. If not, write to the -// Free Software Foundation, 59 Temple Place - Suite 330, Boston, MA -// 02111-1307, USA. -// -// As a special exception, if you include this header file into source -// files to be compiled, this header file does not by itself cause -// the resulting executable to be covered by the GNU General Public -// License. This exception does not however invalidate any other -// reasons why the executable file might be covered by the GNU General -// Public License. -// ----------------------------------------------------------------------- -//frsh_distributed_spare_capacity.h -//============================================== -// ******** ******* ******** ** ** -// **///// /**////** **////// /** /** -// ** /** /** /** /** /** -// ******* /******* /********* /********** -// **//// /**///** ////////** /**//////** -// ** /** //** /** /** /** -// ** /** //** ******** /** /** -// // // // //////// // // -// -// FRSH(FRescor ScHeduler), pronounced "fresh" -//============================================== -#ifndef _FRSH_DISTRIBUTED_SPARE_CAPACITY_H_ -#define _FRSH_DISTRIBUTED_SPARE_CAPACITY_H_ - -#include "frsh_core.h" -#include "frsh_distributed.h" - - -#define FRSH_DISTRIBUTED_SPARE_CAPACITY_MODULE_SUPPORTED 1 - -/** - * @defgroup distribspare Distributed Spare Capacity - * - * This module adds spare-capacity/dynamic reclamation capabilities to - * the distributed module of FRSH. - * - * @{ - **/ - -/** - * frsh_contract_set_granted_capacity_flag() - * - * This operation sets the granted capacity flag in the contract - * parameters object pointed to by contract to the boolean specified in - * granted_capacity_flag. This flag indicates to the scheduler that - * once the negotiation of the respective contract is finished, the - * first values for the budget and period given to the corresponding - * vres must not be changed due to the negotiation or renegotiation - * of any other contract in the system. The period can change, though, - * if a renegotiation or a change of quality and importance is - * requested for the corresponding vres It fails with - * FRSH_ERR_BAD_ARGUMENT if contract is NULL. - **/ -int frsh_contract_set_granted_capacity_flag - (frsh_contract_t *contract, - bool granted_capacity_flag); - -/** - * frsh_contract_get_granted_capacity_flag() - * - * This operation returns in the place pointed to by - * granted_capacity_flag the value of the corresponding flag in the - * contract parameters object pointed to by contract. It fails with - * FRSH_ERR_BAD_ARGUMENT if any of the pointers is NULL - **/ -int frsh_contract_get_granted_capacity_flag - (frsh_contract_t *contract, - bool *granted_capacity_flag); - -/** - * frsh_vres_set_capacity() - * - * This operation is used to return spare capacity that was assigned to - * a vres but that cannot be used due to restrictions in other - * vres of a distributed transaction. This operation changes the - * cycle period and budget of the given vres to the values given in - * new_period and new_budget, respectively. It fails with - * FRSH_ERR_BAD_ARGUMENT if the vres does not have the - * granted_capacity flag set, if the new period is less than the - * current one, or if the new budget is larger than the current one. It - * also fails with the same error number if the new period is greater - * than the maximum period currently specified in the contract - * associated to the vres or, similarly, if the new budget is smaller - * than the minimum budget in the contract. It also fails with the - * same number if the granularity is discrete and the new period and - * budget do not match any of the period-budget pairs in the - * utilization set of the vres. - **/ -int frsh_vres_set_capacity - (frsh_vres_id_t vres, - const struct timespec *new_period, - const struct timespec *new_budget); - -/*@}*/ -#endif // _FRSH_DISTRIBUTED_SPARE_CAPACITY_H_ diff --git a/frsh_distributed_types.h b/frsh_distributed_types.h index 4bb5d83..0043f7b 100644 --- a/frsh_distributed_types.h +++ b/frsh_distributed_types.h @@ -103,7 +103,41 @@ typedef unsigned int frsh_node_address_t; * The actual port number is obtained via a configuration * dependent mapping function **/ -typedef unsigned int frsh_port_t; +typedef unsigned int frsh_stream_id_t; + +/** + * Extra information protocol dependent opaque for the application. + * It can be used in different places: contract negotiation, extra + * endpoint info, extra status info... + **/ +typedef struct _protocol_info_t +{ + void *body; + int size; +} frsh_protocol_info_t; + +/** + * Algorithm used when the queue is full to choose the message to reject + **/ +typedef enum _queue_rejection_policy_t +{ + /** A new message is admitted rejecting the oldest message in the + queue to make room for the newcomer **/ + FRSH_QRP_OLDEST, + + /** Incoming messages are rejected if the queue is full **/ + FRSH_QRP_NEWCOMER +} frsh_queue_rejection_policy_t; + +/** + * Queing information for endpoints + **/ +typedef struct _frsh_endpoint_queueing_info_t +{ + int queue_size; /** Size 0 means that there is no queue **/ + frsh_queue_rejection_policy_t queue_policy; +} frsh_endpoint_queueing_info_t; + /*@}*/ diff --git a/frsh_opaque_types.h b/frsh_opaque_types.h index b23fe49..a214143 100644 --- a/frsh_opaque_types.h +++ b/frsh_opaque_types.h @@ -172,6 +172,16 @@ /** Internal scheduling policy within the vres for hierarchical scheduling systems **/ \ frsh_sched_policy_t policy; \ +\ + /** Protocol info for distributed systems. We store it + as a pointer+size. It's internal meaning is imple- + mentation dependent. **/ \ + frsh_protocol_info_t protocol_info; \ +\ + /** Maximum loss rate + Percentage of packet loss in the network that is + tolerated by the application **/ \ +int max_loss_rate; \ }