* 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 = <network 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
//////////////////////////////////////////////////////////////////////
* @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).
+ *
* @{
**/
/**
* 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,
*
* 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);
/*@}*/
+++ /dev/null
-// -----------------------------------------------------------------------
-// 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_
projects / frescor / frsh-include.git / commitdiff