fres/resalloc/fra_generic.h

   1 /**
   2  * @file   fra_generic.h
   3  * @author Michal Sojka <sojkam1@fel.cvut.cz>
   4  * @date   Mon Nov  3 15:32:54 2008
   5  *
   6  * @brief  FORB interface of FRES Resource Allocator
   7  *
   8  *
   9  */
  10 #ifndef FRA_GENERIC_H
  11 #define FRA_GENERIC_H
  12 #include <fcb.h>
  13 #include <fra.h>
  14 #include <fres_contract.h>
  15 #include <ul_gavlcust.h>
  16 #include <fosa.h>
  17 #include <forb/executor.h>
  18 #include <fres_contract_idl.h>
  19 #include <fres_vres.h>
  20
  21 /** Registry of all virtual resources in an application. */
  22 struct fres_vreses {
  23         fosa_mutex_t mutex;     /**< Mutex for manipulation with vreses tree. If all allocators are executed from one executor, locking can be avoided. */
  24         gavl_cust_root_field_t vreses; /**< Container of all virtual resources */
  25 };
  26
  27 GAVL_CUST_NODE_INT_DEC(fres_vreses_nolock /* cust_prefix */,
  28                        struct fres_vreses /* cust_root_t */,
  29                        struct fres_vres   /* cust_item_t */,
  30                        fres_contract_id_t /* cust_key_t */,
  31                        vreses             /* cust_root_node */,
  32                        node               /* cust_item_node */,
  33                        id                 /* cust_item_key */,
  34                        fres_contract_id_cmp /* cust_cmp_fnc */)
  35
  36 extern struct fres_vreses fres_vreses;
  37
  38
  39 /**
  40  * Structure describing FRES allocator. It is used as a parameter to
  41  * fra_register(), which registeres this allocator with contract
  42  * broker and provides FORB interface to the real allocator.
  43  *
  44  */
  45 struct fres_allocator {
  46         frsh_resource_type_t res_type; /**< Resource type */
  47         frsh_resource_id_t res_id;     /**< Resource ID */
  48         /** @name Simple interface
  49          * The allocator cannot influence the order of applying changes. */
  50         /*@{*/
  51         /**
  52          * Should create the VRES according to the parameters in
  53          * fres_vres::new.
  54          *
  55          * @param vres VRES to create.
  56          * @param priv
  57          *
  58          * @return Zero in case of success, nonzero error code on error.
  59          */
  60         int (*create_vres)(fres_vres_t *vres, void *priv);
  61         /**
  62          * Should change the already crated VRES according to the
  63          * parameters in fres_vres::new. The currenlty allocated
  64          * parameters are in fres_vres::allocated. This function
  65          * should change the fres_vres::perceived to @a fres_vres::new
  66          * at some point in time (depending on the kind of the change)
  67          * as the fres_vres::allocated parameters will be freed after
  68          * the return of this function.
  69          *
  70          * @param vres VRES to change.
  71          * @param priv
  72          *
  73          * @return Zero in case of success, nonzero error code on error.
  74          */
  75         int (*change_vres)(fres_vres_t *vres, void *priv);
  76         /*@}*/
  77         /** @name Full interface
  78          * The allocator can influence the order of applying changes. */
  79         /*@{*/
  80         /**
  81          * A more general (and more compilcated) allocator
  82          * interface. If this field is non-NULL, the simple interface
  83          * is not used.
  84          *
  85          * The advantage of this method is that it can apply the
  86          * changes in whatever order and even in parallel. The new
  87          * version of VRES parameters is stored in fres_vres::new,
  88          * whereas the previous version (if any) is stored in
  89          * fres_vres::allocated. This function should change the
  90          * fres_vres::perceived to @a fres_vres::new at some point in
  91          * time (depending on the kind of the change) as the
  92          * fres_vres::allocated parameters will be freed after the
  93          * return of this function.
  94          *
  95          * @param vreses Array of pointers to VRESes.
  96          * @param length The number of elements in @a vreses.
  97          * @param priv Value of @a priv field in this structure.
  98          *
  99          * @return Zero in case of success, non-zero error code otherwise.
 100          */
 101         int (*apply_vres_changes)(fres_vres_t *vreses[], unsigned length, void *priv);
 102         /*@}*/
 103
 104         /**
 105          *
 106          *
 107          * @param cancel_vres
 108          *
 109          * @return
 110          */
 111         int (*cancel_vres)(fres_vres_t *vres, void *priv);
 112         void *priv;             /**< Pointer to allocator's private data */
 113
 114         /**
 115          * A callback called whenever the resource allocator is to be
 116          * activated by fra_activate().
 117          */
 118         int (*activate_callback)(forb_orb orb);
 119 };
 120
 121 fres_resource_allocator fra_new(forb_orb orb,
 122                                 forb_executor_t *executor,
 123                                 struct fres_allocator *allocator);
 124
 125 void fra_registry_init(forb_orb            orb,
 126                        fres_contract_broker fcb,
 127                        forb_executor_t     *executor);
 128 int fra_register(struct fres_allocator *allocator);
 129 int fra_activate(frsh_resource_type_t res_type,
 130                  frsh_resource_id_t   res_id);
 131
 132 fres_vres_t *fra_get_vres(fres_contract_id_t *id);
 133
 134 #endif