TAO/orbsvcs/orbsvcs/CosLoadBalancing.idl

   1 // -*- IDL -*-
   2
   3 //=============================================================================
   4 /**
   5  *  @file    CosLoadBalancing.idl
   6  *
   7  *  @author Object Management Group
   8  */
   9 //=============================================================================
  10
  11
  12 #ifndef COSLOADBALANCING_IDL
  13 #define COSLOADBALANCING_IDL
  14
  15 #include "PortableGroup.idl"
  16 #include "orb.idl"
  17
  18 /**
  19  * @class CosLoadBalancing
  20  *
  21  * @brief This module defines the interfaces and data types used in
  22  * TAO's Load Balancing service.
  23  * @par
  24  * TAO's Load Balancer manages distribution of requests to replicas of
  25  * a given Object in an effort to ensure that the  applications/hosts
  26  * pointed to by the Object reference are as equally loaded as
  27  * possible, i.e. load balanced.
  28  * @par
  29  * The definition of 'load' is application specific, for example, some
  30  * applications may choose to load balance access to multiple
  31  * dedicated lines, or separate network interfaces, as well as more
  32  * traditional load balancing metrics, such as CPU or power load.
  33  */
  34 module CosLoadBalancing
  35 {
  36   typeprefix CosLoadBalancing "tao.lb";
  37
  38   const IOP::ServiceId LOAD_MANAGED = 123456;  // @todo TBA by OMG
  39
  40   typedef PortableGroup::Location Location;
  41   typedef PortableGroup::Properties Properties;
  42
  43   // Types used for obtaining and/or reporting loads
  44   typedef unsigned long LoadId;
  45
  46   // OMG defined LoadId constants.
  47   const LoadId LoadAverage = 0;
  48   const LoadId Disk = 1;
  49   const LoadId Memory = 2;
  50   const LoadId Network = 3;
  51   const LoadId RequestsPerSecond = 4;
  52
  53   struct Load {
  54     LoadId id;
  55     float value;
  56   };
  57   typedef sequence<Load> LoadList;
  58
  59   exception MonitorAlreadyPresent {};
  60   exception LocationNotFound {};
  61   exception LoadAlertNotFound {};
  62   exception LoadAlertAlreadyPresent {};
  63   exception LoadAlertNotAdded {};
  64
  65   exception StrategyNotAdaptive {};
  66
  67   interface LoadManager;
  68
  69   interface Strategy
  70   {
  71     readonly attribute string name;
  72
  73     Properties get_properties ();
  74
  75     /// Report loads at given location to the LoadManager.
  76     void push_loads (in PortableGroup::Location the_location,
  77                      in LoadList loads)
  78       raises (StrategyNotAdaptive);
  79
  80     /// Get loads, if any, at the given location.  Load balancing
  81     /// strategies may use this method to query loads at specific
  82     /// locations.  Returned loads are the effective loads computed by
  83     /// the Strategy, as opposed to the raw loads maintained by the
  84     /// LoadManager.
  85     LoadList get_loads (in LoadManager load_manager,
  86                         in PortableGroup::Location the_location)
  87       raises (LocationNotFound);
  88
  89     /// Return the next member from the given object group which will
  90     /// requests will be forward to.
  91     Object next_member (in PortableGroup::ObjectGroup object_group,
  92                         in LoadManager load_manager)
  93       raises (PortableGroup::ObjectGroupNotFound,
  94               PortableGroup::MemberNotFound);
  95
  96     /// Ask the Strategy to analyze loads, and enable or disable alerts
  97     /// at object group members residing at appropriate locations.
  98     oneway void analyze_loads (in PortableGroup::ObjectGroup object_group,
  99                                in LoadManager load_manager);
 100
 101     // The loads at the given location should no longer be considered
 102     // when performing load analysis.
 103     // void location_removed (in PortableGroup::Location the_location)
 104     //   raises (LocationNotFound);
 105   };
 106
 107   typedef Strategy CustomStrategy;
 108
 109   /// Property value for built-in load balancing Strategy.
 110   struct StrategyInfo
 111   {
 112     string name;
 113     Properties props;
 114   };
 115
 116   interface LoadAlert
 117   {
 118     /// Forward requests back to the load manager via the object group
 119     /// reference.
 120     void enable_alert ();
 121
 122     /// Stop forwarding requests, and begin accepting them again.
 123     void disable_alert ();
 124   };
 125
 126   /// Interface that all load monitors must implement.
 127   interface LoadMonitor
 128   {
 129     /// Retrieve the location at which the LoadMonitor resides.
 130     readonly attribute Location the_location;
 131
 132     /// Retrieve the current load at the location LoadMonitor resides.
 133     readonly attribute LoadList loads;
 134   };
 135
 136   /// Specification of LoadManager Interface
 137   interface LoadManager
 138     : PortableGroup::PropertyManager,
 139       PortableGroup::ObjectGroupManager,
 140       PortableGroup::GenericFactory
 141   {
 142     /// For the PUSH load monitoring style.
 143     void push_loads (in PortableGroup::Location the_location,
 144                      in LoadList loads);
 145
 146     /// Return the raw loads at the given location, as opposed to the
 147     /// potentially different effective loads returned by the
 148     /// Strategy::get_loads() method.
 149     LoadList get_loads (in PortableGroup::Location the_location)
 150       raises (LocationNotFound);
 151
 152     /// Inform member at given location of load alert condition.
 153     void enable_alert (in PortableGroup::Location the_location)
 154       raises (LoadAlertNotFound);
 155
 156     /// Inform member at given location that load alert condition has
 157     /// passed.
 158     void disable_alert (in PortableGroup::Location the_location)
 159       raises (LoadAlertNotFound);
 160
 161     /// Register a LoadAlert object for the member at the given
 162     /// location.
 163     void register_load_alert (in PortableGroup::Location the_location,
 164                               in LoadAlert load_alert)
 165       raises (LoadAlertAlreadyPresent,
 166               LoadAlertNotAdded);
 167
 168     /// Retrieve the LoadAlert object for the member at the given
 169     /// location.
 170     LoadAlert get_load_alert (in PortableGroup::Location the_location)
 171       raises (LoadAlertNotFound);
 172
 173     /// Remove (de-register) the LoadAlert object for the member at the
 174     /// given location.
 175     void remove_load_alert (in PortableGroup::Location the_location)
 176       raises (LoadAlertNotFound);
 177
 178     // The following load monitor methods are only used for the PULL
 179     // load monitoring style.
 180
 181     /// Register a LoadMonitor object for "pull" monitoring of the
 182     /// given location.
 183     void register_load_monitor (in PortableGroup::Location the_location,
 184                                 in LoadMonitor load_monitor)
 185       raises (MonitorAlreadyPresent);
 186
 187     /// Retrieve the LoadMonitor object for the given location.
 188     LoadMonitor get_load_monitor (in PortableGroup::Location the_location)
 189       raises (LocationNotFound);
 190
 191     /// Remove (de-register) the LoadMonitor object for the given
 192     ///  location.
 193     void remove_load_monitor (in PortableGroup::Location the_location)
 194       raises (LocationNotFound);
 195
 196   };
 197
 198 };
 199
 200 #endif  /* COSLOADBALANCING_IDL */