dtm.h

   1 //----------------------------------------------------------------------
   2 //  Copyright (C) 2006 - 2009 by the FRESCOR consortium:
   3 //
   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
  10 //    ENEA                                   SWEDEN
  11 //    Thales Communication S.A.              FRANCE
  12 //    Visual Tools S.A.                      SPAIN
  13 //    Rapita Systems Ltd                     UK
  14 //    Evidence                               ITALY
  15 //
  16 //    See http://www.frescor.org
  17 //
  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
  21 //        made of this code.
  22 //
  23 //
  24 //  based on previous work (FSF) done in the FIRST project
  25 //
  26 //   Copyright (C) 2005  Mälardalen University, SWEDEN
  27 //                       Scuola Superiore S.Anna, ITALY
  28 //                       Universidad de Cantabria, SPAIN
  29 //                       University of York, UK
  30 //
  31 // This file is part of DTM (Distributed Transaction Manager)
  32 //
  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.
  43 //
  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 // -----------------------------------------------------------------------
  52
  53 /*!
  54  * @file dtm.h
  55  *
  56  * @brief DTM API services
  57  *
  58  * This module contains the functions defined in the DTM API.
  59  *
  60  * @version 0.01
  61  *
  62  * @date 7-Sept-2007
  63  *
  64  * @author Michael Gonzalez Harbour <mgh@unican.es>
  65  * @author Michal Sojka <sojkam1@fel.cvut.cz>
  66  * @author Daniel Sangorrin <daniel.sangorrin@unican.es>
  67  *
  68  */
  69
  70 #ifndef _DTM_H_
  71 #define _DTM_H_
  72
  73 #include "frsh.h"
  74
  75 typedef unsigned int trans_id_t;  /* 0 .. MX_TRANS-1 */
  76
  77 typedef enum {
  78         TRANS_UNKNOWN      =  0,
  79         TRANS_IN_PROGRESS  =  1,
  80         TRANS_ACTIVE       =  2,
  81         TRANS_CANCELLED    =  3,
  82 } trans_status_t;
  83
  84 /**
  85  * dtm_resources_set_processor_vres()
  86  *
  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.
  90  *
  91  **/
  92
  93 extern int dtm_resources_set_processor_vres(const frsh_vres_id_t vres);
  94
  95 /**
  96  * dtm_resources_set_network_vres()
  97  *
  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
 103  * directly.
 104  *
 105  **/
 106
 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);
 110
 111 /**
 112  * dtm_trans_init()
 113  *
 114  * Initialize a new transaction with the given name and maximum number of
 115  * contracts. The newly created transaction will be initialized to contain
 116  * no contracts.
 117  *
 118  **/
 119
 120 extern int dtm_trans_init(const char          *name,
 121                           const unsigned char num_contracts,
 122                           trans_id_t          *trans);
 123
 124 /**
 125  * dtm_trans_add_contract()
 126  *
 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
 133  * or renegotiations.
 134  *
 135  **/
 136
 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);
 141
 142 /**
 143  * dtm_trans_remove_contract()
 144  *
 145  * Remove a contract, identified by its label, from the transaction.
 146  *
 147  **/
 148
 149 extern int dtm_trans_remove_contract(trans_id_t trans,
 150                                      const char *contract_label);
 151
 152 /**
 153  * dtm_trans_destroy()
 154  *
 155  * Destroy a transaction freeing any memory that was allocated to it at
 156  * its creation.
 157  *
 158  **/
 159
 160 extern int dtm_trans_destroy(trans_id_t trans);
 161
 162 /**
 163  * dtm_trans_num_contracts()
 164  *
 165  * Return the current number of contracts in a transaction.
 166  *
 167  **/
 168
 169 extern int dtm_trans_num_contracts(trans_id_t trans, unsigned char *num);
 170
 171 /**
 172  * dtm_trans_get_contract()
 173  *
 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.
 176  *
 177  **/
 178
 179 extern int dtm_trans_get_contract(trans_id_t      trans,
 180                                   unsigned char   index,
 181                                   frsh_contract_t **contract);
 182
 183 /**
 184  * dtm_trans_negotiate()
 185  *
 186  * Negotiate a transaction. This is a blocking call that will not return
 187  * until the negotiation has been completed.
 188  *
 189  **/
 190
 191 extern int dtm_trans_negotiate(trans_id_t trans);
 192
 193 /**
 194  * dtm_trans_cancel()
 195  *
 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.
 199  *
 200  **/
 201
 202 extern int dtm_trans_cancel(trans_id_t trans);
 203
 204 /**
 205  * dtm_trans_renegotiate()
 206  *
 207  * Renegotiate a transaction. This is a blocking call that will not return
 208  * until the negotiation has been completed.
 209  *
 210  **/
 211
 212 extern int dtm_trans_renegotiate(trans_id_t trans);
 213
 214 /**
 215  * dtm_priv_trans_search()
 216  *
 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
 219  * handle.
 220  *
 221  * When allocate_if_miss equals true, it tries to allocate a new transaction
 222  * if the transaction was not found with 0 contracts.
 223  *
 224  **/
 225
 226 extern bool dtm_priv_trans_search(const char            *name,
 227                                   trans_id_t            *trans,
 228                                   const bool            allocate_if_miss);
 229
 230 /**
 231  * dtm_trans_get_status()
 232  *
 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:
 235  *
 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
 240  *
 241  **/
 242
 243 extern int dtm_trans_get_status(const char            *name,
 244                                 trans_status_t        *status);
 245
 246 /**
 247  * dtm_trans_wait_active()
 248  *
 249  * Given a transaction name, wait until it gets active. A handle to the
 250  * transaction is obtained. A timeout may be specified.
 251  *
 252  **/
 253
 254 extern int dtm_trans_wait_active(const char            *name,
 255                                  const struct timespec *timeout,
 256                                  trans_id_t            *trans);
 257
 258 /**
 259  * dtm_trans_get_vres()
 260  *
 261  * Given a transaction handle and a contract label, get the virtual resource
 262  * associated with that contract in the local processor.
 263  *
 264  **/
 265
 266 extern int dtm_trans_get_vres(trans_id_t         trans,
 267                               const char         *contract_label,
 268                               frsh_vres_id_t     *vres);
 269
 270 /**
 271  * dtm_trans_get_period()
 272  *
 273  * Get the current synchronous period of an active transaction, if any.
 274  *
 275  **/
 276
 277 extern int dtm_trans_get_period(trans_id_t      trans,
 278                                 struct timespec *period);
 279
 280 /**
 281  * dtm_init()
 282  *
 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.
 290  *
 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.
 294  *
 295  **/
 296
 297 extern int dtm_init(frsh_stream_id_t stream);
 298
 299 /**
 300  * dtm_init_isdone()
 301  *
 302  * Query about whether the DTM has been initialized or not.
 303  *
 304  **/
 305
 306 extern bool dtm_init_isdone(void);
 307
 308 #endif // _DTM_H_