1 //----------------------------------------------------------------------
2 // Copyright (C) 2006 - 2009 by the FRESCOR consortium:
4 // Universidad de Cantabria, SPAIN
5 // University of York, UK
6 // Scuola Superiore Sant'Anna, ITALY
7 // Kaiserslautern University, GERMANY
8 // Univ. Politecnica Valencia, SPAIN
9 // Czech Technical University in Prague, CZECH REPUBLIC
11 // Thales Communication S.A. FRANCE
12 // Visual Tools S.A. SPAIN
13 // Rapita Systems Ltd UK
16 // See http://www.frescor.org
18 // The FRESCOR project (FP6/2005/IST/5-034026) is funded
19 // in part by the European Union Sixth Framework Programme
20 // The European Union is not liable of any use that may be
24 // based on previous work (FSF) done in the FIRST project
26 // Copyright (C) 2005 Mälardalen University, SWEDEN
27 // Scuola Superiore S.Anna, ITALY
28 // Universidad de Cantabria, SPAIN
29 // University of York, UK
31 // This file is part of DTM (Distributed Transaction Manager)
33 // DTM is free software; you can redistribute it and/or modify it
34 // under terms of the GNU General Public License as published by the
35 // Free Software Foundation; either version 2, or (at your option) any
36 // later version. DTM is distributed in the hope that it will be
37 // useful, but WITHOUT ANY WARRANTY; without even the implied warranty
38 // of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
39 // General Public License for more details. You should have received a
40 // copy of the GNU General Public License along with DTM; see file
41 // COPYING. If not, write to the Free Software Foundation, 675 Mass Ave,
42 // Cambridge, MA 02139, USA.
44 // As a special exception, including DTM header files in a file,
45 // instantiating DTM generics or templates, or linking other files
46 // with DTM objects to produce an executable application, does not
47 // by itself cause the resulting executable application to be covered
48 // by the GNU General Public License. This exception does not
49 // however invalidate any other reasons why the executable file might be
50 // covered by the GNU Public License.
51 // -----------------------------------------------------------------------
56 * @brief DTM API services
58 * This module contains the functions defined in the DTM API.
64 * @author Michael Gonzalez Harbour <mgh@unican.es>
65 * @author Michal Sojka <sojkam1@fel.cvut.cz>
66 * @author Daniel Sangorrin <daniel.sangorrin@unican.es>
75 typedef unsigned int trans_id_t; /* 0 .. MX_TRANS-1 */
79 TRANS_IN_PROGRESS = 1,
85 * dtm_resources_set_processor_vres()
87 * Set the virtual resource that will be used in the local processor by the
88 * manager thread of the agent of the DTM. This must be a valid virtual
89 * resource obtained form the negotiation of a contract.
93 extern int dtm_resources_set_processor_vres(const frsh_vres_id_t vres);
96 * dtm_resources_set_network_vres()
98 * Set the virtual resource that will be used by the local DTM agent to send
99 * messages to the specified destination address. This must be a valid virtual
100 * resource obtained from the negotiation of a network contract, and must be
101 * compatible with the current system topology. Multiple calls to this
102 * operation may be needed, one for each processing node that is connected
107 extern int dtm_resources_set_network_vres(const frsh_resource_id_t network,
108 const frsh_resource_id_t dest,
109 const frsh_vres_id_t vres);
114 * Initialize a new transaction with the given name and maximum number of
115 * contracts. The newly created transaction will be initialized to contain
120 extern int dtm_trans_init(const char *name,
121 const unsigned char num_contracts,
125 * dtm_trans_add_contract()
127 * Add a reference to a contract to the given transaction together with
128 * the node in which that contract needs to be negotiated, and a boolean
129 * indicating whether or not the period needs to be synchronous with
130 * respect to other synchronous-period contracts in the transaction. Just
131 * the reference to the contract is copied, not the full contract information,
132 * and thus future changes to the contract may affect future negotiations
137 extern int dtm_trans_add_contract(trans_id_t trans,
138 frsh_contract_t *contract,
139 frsh_resource_id_t node,
140 bool is_synch_period);
143 * dtm_trans_remove_contract()
145 * Remove a contract, identified by its label, from the transaction.
149 extern int dtm_trans_remove_contract(trans_id_t trans,
150 const char *contract_label);
153 * dtm_trans_destroy()
155 * Destroy a transaction freeing any memory that was allocated to it at
160 extern int dtm_trans_destroy(trans_id_t trans);
163 * dtm_trans_num_contracts()
165 * Return the current number of contracts in a transaction.
169 extern int dtm_trans_num_contracts(trans_id_t trans, unsigned char *num);
172 * dtm_trans_get_contract()
174 * Given an index, return a reference to the contract stored in that index.
175 * This operation is used to iterate over the contracts of a transaction.
179 extern int dtm_trans_get_contract(trans_id_t trans,
181 frsh_contract_t **contract);
184 * dtm_trans_negotiate()
186 * Negotiate a transaction. This is a blocking call that will not return
187 * until the negotiation has been completed.
191 extern int dtm_trans_negotiate(trans_id_t trans);
196 * Cancel a transaction, by cancelling all the virtual resources that were
197 * associated with it. Cancellation has to be invoked from the same node
198 * where the transaction was negotiated.
202 extern int dtm_trans_cancel(trans_id_t trans);
205 * dtm_trans_renegotiate()
207 * Renegotiate a transaction. This is a blocking call that will not return
208 * until the negotiation has been completed.
212 extern int dtm_trans_renegotiate(trans_id_t trans);
215 * dtm_priv_trans_search()
217 * Internal function that searches a transaction by its name. It returns
218 * true if the transaction exists and sets the parameter to the transaction
221 * When allocate_if_miss equals true, it tries to allocate a new transaction
222 * if the transaction was not found with 0 contracts.
226 extern bool dtm_priv_trans_search(const char *name,
228 const bool allocate_if_miss);
231 * dtm_trans_get_status()
233 * Given a transaction name, get its status. This operation can be created
234 * in any node in the system. The status is an enumeration:
236 * - unknown: the current node has not yet been involved in the transaction
237 * - in_progress: the negotiation is in progress
238 * - active: the transaction was successfully negotiated and is active
239 * - cancelled: the transaction was cancelled
243 extern int dtm_trans_get_status(const char *name,
244 trans_status_t *status);
247 * dtm_trans_wait_active()
249 * Given a transaction name, wait until it gets active. A handle to the
250 * transaction is obtained. A timeout may be specified.
254 extern int dtm_trans_wait_active(const char *name,
255 const struct timespec *timeout,
259 * dtm_trans_get_vres()
261 * Given a transaction handle and a contract label, get the virtual resource
262 * associated with that contract in the local processor.
266 extern int dtm_trans_get_vres(trans_id_t trans,
267 const char *contract_label,
268 frsh_vres_id_t *vres);
271 * dtm_trans_get_period()
273 * Get the current synchronous period of an active transaction, if any.
277 extern int dtm_trans_get_period(trans_id_t trans,
278 struct timespec *period);
283 * Initialize the distributed transaction manager in the local node.
284 * The stream Id to be used for DTM messages is specified as an argument.
285 * In first place, the operation creates all the necessary system resources
286 * (threads and communication endpoints) and binds them to the resources that
287 * were previously assigned locally to the DTM. Then, it performs the
288 * initialization process that synchronizes all the nodes, waiting until all
289 * of them are ready to work.
291 * TODO: The wait can be specified with a timeout,
292 * after which the operation would deallocate the allocated resources
293 * and return an error indication.
297 extern int dtm_init(frsh_stream_id_t stream);
302 * Query about whether the DTM has been initialized or not.
306 extern bool dtm_init_isdone(void);