frsh_transaction.h

   1 /**************************************************************************/
   2 /* Copyright (C) 2010 Czech Technical University in Prague                */
   3 /*                                                                        */
   4 /*  This file is part of FRSH (FRescor ScHeduler)                         */
   5 /*                                                                        */
   6 /* FRSH is free software; you can redistribute it and/or modify it        */
   7 /* under terms of the GNU General Public License as published by the      */
   8 /* Free Software Foundation; either version 2, or (at your option) any    */
   9 /* later version.  FRSH is distributed in the hope that it will be        */
  10 /* useful, but WITHOUT ANY WARRANTY; without even the implied warranty    */
  11 /* of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU    */
  12 /* General Public License for more details. You should have received a    */
  13 /* copy of the GNU General Public License along with FRSH; see file       */
  14 /* COPYING. If not, write to the Free Software Foundation, 675 Mass Ave,  */
  15 /* Cambridge, MA 02139, USA.                                              */
  16 /*                                                                        */
  17 /* As a special exception, including FRSH header files in a file,         */
  18 /* instantiating FRSH generics or templates, or linking other files       */
  19 /* with FRSH objects to produce an executable application, does not       */
  20 /* by itself cause the resulting executable application to be covered     */
  21 /* by the GNU General Public License. This exception does not             */
  22 /* however invalidate any other reasons why the executable file might be  */
  23 /* covered by the GNU Public License.                                     */
  24 /**************************************************************************/
  25
  26
  27 #ifndef _FRSH_TRANSACTION_H_
  28 #define _FRSH_TRANSACTION_H_
  29
  30 #include "frsh_cpp_macros.h"
  31 #include "frsh_core_types.h"
  32
  33 FRSH_CPP_BEGIN_DECLS
  34
  35 struct fres_transaction_t_type;
  36
  37 /* frsh_transaction_t is a pointer to resemble how frsh_contract_t is
  38  * defined. */
  39 typedef struct fres_transaction_t_type *frsh_transaction_t;
  40
  41 /**
  42  * Initialize a transaction.
  43  *
  44  * @param transaction
  45  *
  46  * @param name The name of the transaction which can be used in
  47  * frsh_transaction_wait_for_name().
  48  *
  49  * @return Zero on success, non-zero error code on return.
  50  */
  51 int
  52 frsh_transaction_init(frsh_transaction_t *transaction,
  53                       char *name);
  54
  55 /**
  56  * Deallocates memory of the transaction object.
  57  *
  58  * @param transaction
  59  */
  60 void
  61 frsh_transaction_destroy(frsh_transaction_t *transaction);
  62
  63 /**
  64  * Add a contract to the transaction.
  65  *
  66  * @param transaction Transaction
  67  * @param contract Contract to add
  68  *
  69  * @param index Index of the contract within the transaction. The
  70  * index is used in frsh_transaction_alloc_vres(). The first added
  71  * contract must have zero index, the second one, etc.
  72  *
  73  * @return Zero on success, non-zero error code on return.
  74  */
  75 int
  76 frsh_transaction_add_contract(frsh_transaction_t *transaction,
  77                               frsh_contract_t *contract,
  78                               int index);
  79
  80 /**
  81  * Negotiates a multi-resource transaction.
  82  *
  83  * No resource is allocated in this step of negotiation. Use
  84  * frsh_transaction_alloc_vres() to allocate resource and use it in
  85  * application.
  86  *
  87  * @param trans Transaction with added contracts.
  88  *
  89  * @return Zero on success, non-zero error code on return.
  90  */
  91 int
  92 frsh_transaction_negotiate(frsh_transaction_t *trans);
  93
  94 /**
  95  * Cancels a negotiated transaction.
  96  *
  97  * @param trans
  98  *
  99  * @return Zero on success, non-zero error code on return.
 100  */
 101 int
 102 frsh_transaction_cancel(frsh_transaction_t *trans);
 103
 104 /**
 105  * Retrieves a negotiated transaction by name.
 106  *
 107  * Applications that do not initiate transaction negotiation need a
 108  * way to participate in the transaction. This function waits until
 109  * the transaction with a given @a name is negotiated and then returns
 110  * the @a transaction object.
 111  *
 112  * @param name
 113  * @param transaction
 114  *
 115  * @return Zero on success, non-zero error code on return.
 116  */
 117 int
 118 frsh_transaction_wait_for_name(frsh_transaction_t *transaction,
 119                                const char *name);
 120 /**
 121  * Allocates VRES from the negotiated transaction.
 122  *
 123  * Given the transaction object and an index (see
 124  * frsh_transaction_add_contract()) this function requests allocation
 125  * of the
 126  *
 127  * @param t
 128  * @param vres
 129  * @param index
 130  *
 131  * @return
 132  */
 133 int
 134 frsh_transaction_alloc_vres(frsh_transaction_t *t,
 135                             int index,
 136                             frsh_vres_id_t *vres);
 137
 138 FRSH_CPP_END_DECLS
 139
 140 #endif // _FRSH_TRANSACTION_H_