--- /dev/null
+//----------------------------------------------------------------------
+// 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 <mgh@unican.es>
+ * @author Michal Sojka <sojkam1@fel.cvut.cz>
+ * @author Daniel Sangorrin <daniel.sangorrin@unican.es>
+ *
+ */
+
+#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_
projects / frescor / frsh-include.git / commitdiff