fres/cbroker/fcb.idl

   1 ////////////////////////////////////////////////////////////////////////////
   2 // ---------------------------------------------------------------------- //
   3 // Copyright (C) 2006 - 2008 FRESCOR consortium partners:                 //
   4 //                                                                        //
   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                //
  11 //   ENEA                                   SWEDEN                        //
  12 //   Thales Communication S.A.              FRANCE                        //
  13 //   Visual Tools S.A.                      SPAIN                         //
  14 //   Rapita Systems Ltd                     UK                            //
  15 //   Evidence                               ITALY                         //
  16 //                                                                        //
  17 //   See http://www.frescor.org for a link to partners' websites          //
  18 //                                                                        //
  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.                                               //
  23 //                                                                        //
  24 //                                                                        //
  25 // based on previous work (FSF) done in the FIRST project                 //
  26 //                                                                        //
  27 //  Copyright (C) 2005  Mälardalen University, SWEDEN                    //
  28 //                      Scuola Superiore S.Anna, ITALY                    //
  29 //                      Universidad de Cantabria, SPAIN                   //
  30 //                      University of York, UK                            //
  31 //                                                                        //
  32 //  FSF API web pages: http:marte.unican.es/fsf/docs                      //
  33 //                     http:shark.sssup.it/contrib/first/docs/            //
  34 //                                                                        //
  35 //  This file is part of FORB (Frescor Object Request Broker)             //
  36 //                                                                        //
  37 // FORB is free software; you can redistribute it and/or modify it        //
  38 // under terms of the GNU General Public License as published by the      //
  39 // Free Software Foundation; either version 2, or (at your option) any    //
  40 // later version.  FORB is distributed in the hope that it will be        //
  41 // useful, but WITHOUT ANY WARRANTY; without even the implied warranty    //
  42 // of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU    //
  43 // General Public License for more details. You should have received a    //
  44 // copy of the GNU General Public License along with FORB; see file       //
  45 // COPYING. If not, write to the Free Software Foundation, 675 Mass Ave,  //
  46 // Cambridge, MA 02139, USA.                                              //
  47 //                                                                        //
  48 // As a special exception, including FORB header files in a file,         //
  49 // instantiating FORB generics or templates, or linking other files       //
  50 // with FORB objects to produce an executable application, does not       //
  51 // by itself cause the resulting executable application to be covered     //
  52 // by the GNU General Public License. This exception does not             //
  53 // however invalidate any other reasons why the executable file might be  //
  54 // covered by the GNU Public License.                                     //
  55 ////////////////////////////////////////////////////////////////////////////
  56
  57 #ifndef _CM_IDL
  58 #define _CM_IDL
  59
  60 #include "../contract/fres_contract_idl.idl"
  61 #include "../contract/fres_blocks.idl"
  62 #include "../resmng/frm.idl"
  63 #include "../resalloc/fra.idl"
  64
  65 module fres {
  66
  67         /** Description of a resource */
  68         struct resource_desc {
  69                 /** Manager */
  70                 resource_manager     manager;
  71                 string               name; /**< Human understandable name of the resource (used by frm_gui) */
  72         };
  73
  74         struct resource {
  75                 frsh_resource_type_t restype;
  76                 frsh_resource_id_t   resid;
  77                 resource_desc        desc;
  78         };
  79
  80         typedef sequence<resource> resource_seq;
  81
  82         interface contract_broker {
  83                 const string reg_name = "fcb";
  84                 /**
  85                  * Registers a resource with the contract broker
  86                  *
  87                  * @param restype
  88                  * @param resid
  89                  * @param res_desc Description of the resource
  90                  *
  91                  * @return Zero on success, non-zero error code on error.
  92                  */
  93                 long register_resource(in frsh_resource_type_t restype,
  94                                        in frsh_resource_id_t   resid,
  95                                        in resource_desc        res_desc);
  96
  97                 /**
  98                  * Registers a resource allocator with the contract broker
  99                  *
 100                  * @param restype
 101                  * @param resid
 102                  * @param rs_obj
 103                  *
 104                  * @return Zero on success, non-zero error code on error.
 105                  */
 106                 long register_allocator(in frsh_resource_type_t restype,
 107                                         in frsh_resource_id_t   resid,
 108                                         in resource_allocator   rs_obj);
 109
 110                 long deregister_allocator(in resource_allocator rs_obj);
 111
 112                 /**
 113                  * This function performs a set of negotiation
 114                  * operations with one resource. The oprations can
 115                  * include: adding new contracts (neg), modifying
 116                  * existing vres (reneg) or cancelling existing vres
 117                  * (cancel). It is guarantied that either all
 118                  * operation will be completed or none of them.
 119                  *
 120                  * @param[in] contracts Contract(s) to negotiate,
 121                  * renegotiate or cancel. The operation on the
 122                  * contract is determined as follows:
 123                  * - neg: contracts without ID
 124                  * - cancel: contracts with an ID and without any block
 125                  * - reneg: contracts with ID and some blocks (the old
 126                  *   contract will we replaced by the new one).
 127                  *
 128                  * @param[out] ids IDs of the newly negotiated
 129                  * contracts, if negotiation was successful. Ordering
 130                  * of IDs is the same as in @a contracts.
 131                  *
 132                  * @return Zero if all operations were successfully
 133                  * carried out, non-zero code on error or when
 134                  * negotiation failed.
 135                  */
 136                 long negotiate_contracts(in contract::ptr_seq contracts, out contract::id_seq ids);
 137
 138                 /**
 139                  * Redistributes spare capacity for a given resource.
 140                  * This is meant as a support for resources with
 141                  * variable capacity (WiFi) as a mean for applications
 142                  * to adapt to the changed capacity.
 143                  *
 144                  * @param restype For which resource to perform
 145                  * redistribution.
 146                  */
 147                 void redistribute_spare_capacity(in frsh_resource_type_t restype,
 148                                                  in frsh_resource_id_t   resid);
 149
 150                 /**
 151                  * Returns sequence of registered resources.
 152                  *
 153                  * @param[out] resources
 154                  */
 155                 void get_resources(out resource_seq resources);
 156         };
 157 };
 158
 159 #endif