1 /**************************************************************************/
2 /* ---------------------------------------------------------------------- */
3 /* Copyright (C) 2006 - 2008 FRESCOR consortium partners: */
5 /* Universidad de Cantabria, SPAIN */
6 /* University of York, UK */
7 /* Scuola Superiore Sant'Anna, ITALY */
8 /* Kaiserslautern University, GERMANY */
9 /* Univ. Politécnica Valencia, SPAIN */
10 /* Czech Technical University in Prague, CZECH REPUBLIC */
12 /* Thales Communication S.A. FRANCE */
13 /* Visual Tools S.A. SPAIN */
14 /* Rapita Systems Ltd UK */
17 /* See http://www.frescor.org for a link to partners' websites */
19 /* FRESCOR project (FP6/2005/IST/5-034026) is funded */
20 /* in part by the European Union Sixth Framework Programme */
21 /* The European Union is not liable of any use that may be */
22 /* made of this code. */
25 /* This file is part of FRSH (FRescor ScHeduler) */
27 /* FRSH is free software; you can redistribute it and/or modify it */
28 /* under terms of the GNU General Public License as published by the */
29 /* Free Software Foundation; either version 2, or (at your option) any */
30 /* later version. FRSH is distributed in the hope that it will be */
31 /* useful, but WITHOUT ANY WARRANTY; without even the implied warranty */
32 /* of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU */
33 /* General Public License for more details. You should have received a */
34 /* copy of the GNU General Public License along with FRSH; see file */
35 /* COPYING. If not, write to the Free Software Foundation, 675 Mass Ave, */
36 /* Cambridge, MA 02139, USA. */
38 /* As a special exception, including FRSH header files in a file, */
39 /* instantiating FRSH generics or templates, or linking other files */
40 /* with FRSH objects to produce an executable application, does not */
41 /* by itself cause the resulting executable application to be covered */
42 /* by the GNU General Public License. This exception does not */
43 /* however invalidate any other reasons why the executable file might be */
44 /* covered by the GNU Public License. */
45 /**************************************************************************/
49 * @author Michal Sojka <sojkam1@fel.cvut.cz>
50 * @date Mon Nov 3 15:32:54 2008
52 * @brief FORB interface of FRES Resource Allocator
60 #include <fres_contract.h>
61 #include <ul_gavlcust.h>
63 #include <forb/executor.h>
64 #include <fres_contract_idl.h>
65 #include <fres_vres.h>
67 /** Registry of all virtual resources in an application. */
69 fosa_mutex_t mutex; /**< Mutex for manipulation with vreses tree. If all allocators are executed from one executor, locking can be avoided. */
70 gavl_cust_root_field_t vreses; /**< Container of all virtual resources */
73 GAVL_CUST_NODE_INT_DEC(fres_vreses_nolock /* cust_prefix */,
74 struct fres_vreses /* cust_root_t */,
75 struct fres_vres /* cust_item_t */,
76 fres_contract_id_t /* cust_key_t */,
77 vreses /* cust_root_node */,
78 node /* cust_item_node */,
79 id /* cust_item_key */,
80 fres_contract_id_cmp /* cust_cmp_fnc */)
82 extern struct fres_vreses fres_vreses;
85 fres_vreses_find_label(fres_block_label *label, fres_block_resource *res);
87 /** Registry of all threads in an application that are bound to a VRES. */
88 struct fres_threads_vres {
89 fosa_mutex_t mutex; /**< Mutex for manipulation with vreses tree. If all allocators are executed from one executor, locking can be avoided. */
90 gavl_cust_root_field_t threads; /**< Container of all virtual resources */
93 GAVL_CUST_NODE_INT_DEC(fres_threads_vres_nolock /* cust_prefix */,
94 struct fres_threads_vres /* cust_root_t */,
95 struct fres_thread_vres /* cust_item_t */,
96 fres_thread_vres_key_t /* cust_key_t */,
97 threads /* cust_root_node */,
98 node /* cust_item_node */,
99 thread_vres /* cust_item_key */,
100 fres_thread_vres_cmp /* cust_cmp_fnc */)
102 extern struct fres_threads_vres fres_threads_vres;
106 * Structure describing FRES allocator. It is used as a parameter to
107 * fra_register(), which registeres this allocator with contract
108 * broker and provides FORB interface to the real allocator.
111 struct fres_allocator {
112 frsh_resource_type_t res_type; /**< Resource type */
113 frsh_resource_id_t res_id; /**< Resource ID */
114 /** @name Simple interface
115 * The allocator cannot influence the order of applying changes. */
118 * Should create the VRES according to the parameters in
121 * @param vres VRES to create.
122 * @param priv User supplied pointer registered by fra_register()
124 * @return Zero in case of success, nonzero error code on error.
126 int (*create_vres)(fres_vres_t *vres, void *priv);
128 * Should change the already crated VRES according to the
129 * parameters in fres_vres::new. The currenlty allocated
130 * parameters are in fres_vres::allocated. This function
131 * should change the fres_vres::perceived to @a fres_vres::new
132 * at some point in time (depending on the kind of the change).
133 * The fres_vres::allocated parameters will be freed after
134 * the return of this function and then fres_vres::allocated
135 * will be set to fres_vres::new.
137 * @param vres VRES to change.
138 * @param priv User supplied pointer registered by fra_register()
140 * @return Zero in case of success, nonzero error code on error.
142 int (*change_vres)(fres_vres_t *vres, void *priv);
146 * @param cancel_vres VRES to cancel
148 * @return Zero on succaess, non-zero error code on error.
150 int (*cancel_vres)(fres_vres_t *vres, void *priv);
153 /** @name Full interface
155 * Full interface provides a way for the allocator to
156 * influence the order of applying changes.
160 * A more general (and more compilcated) allocator
161 * interface. If this field is non-NULL, the simple interface
164 * The advantage of this method is that it can apply the
165 * changes in whatever order and even in parallel. The new
166 * version of VRES parameters is stored in fres_vres::new,
167 * whereas the previous version (if any) is stored in
168 * fres_vres::allocated. This function should change the
169 * fres_vres::perceived to @a fres_vres::new at some point in
170 * time (depending on the kind of the change) as the
171 * fres_vres::allocated parameters will be freed after the
172 * return of this function. When the fres_vres::new contains
173 * no blocks, the VRES should be canceled.
175 * @param vreses Array of pointers to VRESes.
176 * @param length The number of elements in @a vreses.
177 * @param priv Value of @a priv field in this structure.
179 * @return Zero in case of success, non-zero error code otherwise.
181 int (*apply_vres_changes)(fres_vres_t *vreses[], unsigned length, void *priv);
184 void *priv; /**< Pointer to allocator's private data */
187 * A callback called whenever the resource allocator is to be
188 * activated by fra_activate().
190 int (*activate_callback)(forb_orb orb);
193 fres_resource_allocator fra_new(forb_orb orb,
194 forb_executor_t *executor,
195 struct fres_allocator *allocator);
197 void fra_registry_init(forb_orb orb,
198 fres_contract_broker fcb,
199 forb_executor_t *executor);
200 int fra_register(struct fres_allocator *allocator);
201 int fra_activate(frsh_resource_type_t res_type,
202 frsh_resource_id_t res_id);
204 fres_vres_t *fra_get_vres(fres_contract_id_t *id);
206 int fra_insert_thread_vres(const fosa_thread_id_t *id,
209 int fra_delete_thread_vres(const fosa_thread_id_t *id,
211 fres_thread_vres_t *fra_get_thread_vres(const fosa_thread_id_t *id,
213 fres_vres_t *fra_get_vres_thread_vres(const fosa_thread_id_t *id,