From: Michal Sojka Date: Mon, 21 Jun 2010 11:50:04 +0000 (+0200) Subject: Add distributed transaction manager (dtm) header X-Git-Url: https://rtime.felk.cvut.cz/gitweb/frescor/frsh-include.git/commitdiff_plain/af6c4fb93901005d070e2ebf2153272c3acb3ed1 Add distributed transaction manager (dtm) header This is taken from FRESCOR Subversion repository --- diff --git a/dtm.h b/dtm.h new file mode 100644 index 0000000..e8e27ea --- /dev/null +++ b/dtm.h @@ -0,0 +1,308 @@ +//---------------------------------------------------------------------- +// Copyright (C) 2006 - 2009 by the FRESCOR consortium: +// +// Universidad de Cantabria, SPAIN +// University of York, UK +// Scuola Superiore Sant'Anna, ITALY +// Kaiserslautern University, GERMANY +// Univ. Politecnica 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 +// +// The 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 +// +// This file is part of DTM (Distributed Transaction Manager) +// +// DTM is free software; you can redistribute it and/or modify it +// under terms of the GNU General Public License as published by the +// Free Software Foundation; either version 2, or (at your option) any +// later version. DTM 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 along with DTM; see file +// COPYING. If not, write to the Free Software Foundation, 675 Mass Ave, +// Cambridge, MA 02139, USA. +// +// As a special exception, including DTM header files in a file, +// instantiating DTM generics or templates, or linking other files +// with DTM objects to produce an executable application, does not +// by itself cause the resulting executable application 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 Public License. +// ----------------------------------------------------------------------- + +/*! + * @file dtm.h + * + * @brief DTM API services + * + * This module contains the functions defined in the DTM API. + * + * @version 0.01 + * + * @date 7-Sept-2007 + * + * @author Michael Gonzalez Harbour + * @author Michal Sojka + * @author Daniel Sangorrin + * + */ + +#ifndef _DTM_H_ +#define _DTM_H_ + +#include "frsh.h" + +typedef unsigned int trans_id_t; /* 0 .. MX_TRANS-1 */ + +typedef enum { + TRANS_UNKNOWN = 0, + TRANS_IN_PROGRESS = 1, + TRANS_ACTIVE = 2, + TRANS_CANCELLED = 3, +} trans_status_t; + +/** + * dtm_resources_set_processor_vres() + * + * Set the virtual resource that will be used in the local processor by the + * manager thread of the agent of the DTM. This must be a valid virtual + * resource obtained form the negotiation of a contract. + * + **/ + +extern int dtm_resources_set_processor_vres(const frsh_vres_id_t vres); + +/** + * dtm_resources_set_network_vres() + * + * Set the virtual resource that will be used by the local DTM agent to send + * messages to the specified destination address. This must be a valid virtual + * resource obtained from the negotiation of a network contract, and must be + * compatible with the current system topology. Multiple calls to this + * operation may be needed, one for each processing node that is connected + * directly. + * + **/ + +extern int dtm_resources_set_network_vres(const frsh_resource_id_t network, + const frsh_resource_id_t dest, + const frsh_vres_id_t vres); + +/** + * dtm_trans_init() + * + * Initialize a new transaction with the given name and maximum number of + * contracts. The newly created transaction will be initialized to contain + * no contracts. + * + **/ + +extern int dtm_trans_init(const char *name, + const unsigned char num_contracts, + trans_id_t *trans); + +/** + * dtm_trans_add_contract() + * + * Add a reference to a contract to the given transaction together with + * the node in which that contract needs to be negotiated, and a boolean + * indicating whether or not the period needs to be synchronous with + * respect to other synchronous-period contracts in the transaction. Just + * the reference to the contract is copied, not the full contract information, + * and thus future changes to the contract may affect future negotiations + * or renegotiations. + * + **/ + +extern int dtm_trans_add_contract(trans_id_t trans, + frsh_contract_t *contract, + frsh_resource_id_t node, + bool is_synch_period); + +/** + * dtm_trans_remove_contract() + * + * Remove a contract, identified by its label, from the transaction. + * + **/ + +extern int dtm_trans_remove_contract(trans_id_t trans, + const char *contract_label); + +/** + * dtm_trans_destroy() + * + * Destroy a transaction freeing any memory that was allocated to it at + * its creation. + * + **/ + +extern int dtm_trans_destroy(trans_id_t trans); + +/** + * dtm_trans_num_contracts() + * + * Return the current number of contracts in a transaction. + * + **/ + +extern int dtm_trans_num_contracts(trans_id_t trans, unsigned char *num); + +/** + * dtm_trans_get_contract() + * + * Given an index, return a reference to the contract stored in that index. + * This operation is used to iterate over the contracts of a transaction. + * + **/ + +extern int dtm_trans_get_contract(trans_id_t trans, + unsigned char index, + frsh_contract_t **contract); + +/** + * dtm_trans_negotiate() + * + * Negotiate a transaction. This is a blocking call that will not return + * until the negotiation has been completed. + * + **/ + +extern int dtm_trans_negotiate(trans_id_t trans); + +/** + * dtm_trans_cancel() + * + * Cancel a transaction, by cancelling all the virtual resources that were + * associated with it. Cancellation has to be invoked from the same node + * where the transaction was negotiated. + * + **/ + +extern int dtm_trans_cancel(trans_id_t trans); + +/** + * dtm_trans_renegotiate() + * + * Renegotiate a transaction. This is a blocking call that will not return + * until the negotiation has been completed. + * + **/ + +extern int dtm_trans_renegotiate(trans_id_t trans); + +/** + * dtm_priv_trans_search() + * + * Internal function that searches a transaction by its name. It returns + * true if the transaction exists and sets the parameter to the transaction + * handle. + * + * When allocate_if_miss equals true, it tries to allocate a new transaction + * if the transaction was not found with 0 contracts. + * + **/ + +extern bool dtm_priv_trans_search(const char *name, + trans_id_t *trans, + const bool allocate_if_miss); + +/** + * dtm_trans_get_status() + * + * Given a transaction name, get its status. This operation can be created + * in any node in the system. The status is an enumeration: + * + * - unknown: the current node has not yet been involved in the transaction + * - in_progress: the negotiation is in progress + * - active: the transaction was successfully negotiated and is active + * - cancelled: the transaction was cancelled + * + **/ + +extern int dtm_trans_get_status(const char *name, + trans_status_t *status); + +/** + * dtm_trans_wait_active() + * + * Given a transaction name, wait until it gets active. A handle to the + * transaction is obtained. A timeout may be specified. + * + **/ + +extern int dtm_trans_wait_active(const char *name, + const struct timespec *timeout, + trans_id_t *trans); + +/** + * dtm_trans_get_vres() + * + * Given a transaction handle and a contract label, get the virtual resource + * associated with that contract in the local processor. + * + **/ + +extern int dtm_trans_get_vres(trans_id_t trans, + const char *contract_label, + frsh_vres_id_t *vres); + +/** + * dtm_trans_get_period() + * + * Get the current synchronous period of an active transaction, if any. + * + **/ + +extern int dtm_trans_get_period(trans_id_t trans, + struct timespec *period); + +/** + * dtm_init() + * + * Initialize the distributed transaction manager in the local node. + * The stream Id to be used for DTM messages is specified as an argument. + * In first place, the operation creates all the necessary system resources + * (threads and communication endpoints) and binds them to the resources that + * were previously assigned locally to the DTM. Then, it performs the + * initialization process that synchronizes all the nodes, waiting until all + * of them are ready to work. + * + * TODO: The wait can be specified with a timeout, + * after which the operation would deallocate the allocated resources + * and return an error indication. + * + **/ + +extern int dtm_init(frsh_stream_id_t stream); + +/** + * dtm_init_isdone() + * + * Query about whether the DTM has been initialized or not. + * + **/ + +extern bool dtm_init_isdone(void); + +#endif // _DTM_H_