TAO/orbsvcs/LoadBalancer/README

   1 This directory contains the sources for two binaries:
   2
   3   1) LoadManager
   4   2) LoadMonitor
   5
   6 Descriptions of each follow.
   7
   8 LoadManager
   9 ===========
  10 The "LoadManager" binary is the stand-alone load balancing/managing
  11 service.
  12
  13 A listing of available "LoadManager" command line options is available
  14 by invoking the "LoadManager" binary with the "-h" command line option.
  15
  16 Usage
  17 -----
  18 The below comments assume a non-adaptive load balancing configuration.
  19 Documentation on adaptive load balancing will be added in the future.
  20
  21 Approach 1:  Portable Approach
  22 ..............................
  23
  24 1. Start the `LoadManager' binary in $TAO_ROOT/orbsvcs/LoadBalancer.
  25
  26 2. In your server, obtain a reference to the "LoadManager" object
  27    using the canonical resolve_initial_references() mechanism.  Don't
  28    forget to pass your server the appropriate
  29    "-ORBInitRef LoadManager=..." ORB option.
  30
  31 3. One (not more!) of your servers must create an "object group."  For
  32    example, to create an object group that your application will
  33    populate (i.e. "application controlled" membership, as opposed to
  34    "infrastructure controlled membership):
  35
  36         // The object group will contain members of this type.
  37         const char * repository_id = "IDL:MyObject:1.0";
  38
  39         PortableGroup::Criteria criteria (1);
  40         criteria.length (1);
  41
  42         PortableGroup::Property & property = criteria[0];
  43         property.nam.length (1);
  44
  45         property.nam[0].id =
  46           CORBA::string_dup ("org.omg.PortableGroup.MembershipStyle");
  47
  48         // Configure for application-controlled membership.
  49         PortableGroup::MembershipStyleValue msv =
  50           PortableGroup::MEMB_APP_CTRL;
  51         property.val <<= msv;
  52
  53         PortableGroup::GenericFactory::FactoryCreationId_var fcid;
  54
  55         CORBA::Object_var group =
  56           load_manager->create_object (repository_id,
  57                                        criteria,
  58                                        fcid.out ());
  59
  60    You then "export" the "group" object reference to your clients as
  61    you would with any other object reference, such as those returned
  62    from _this().  You can for example call object_to_string() on the
  63    above "group" reference.  You can even put it into any Naming
  64    Service, not just TAO's.
  65
  66    Note that the default load balancing strategy is "Random," which is
  67    non-adaptive.  It is currently possible to override it with a
  68    custom one but that functionality hasn't been fully tested yet.  If
  69    you want to know how to do that, please let me know on the mailing
  70    list so that others may benefit, too.
  71
  72 4. Once you've created the object group, you need to populate it with
  73    your object group members, i.e. your objects:
  74
  75         CORBA::Object_var member = my_servant._this ();
  76
  77         PortableGroup::Location location (1);
  78         location.length (1);
  79
  80         // Location this member resides at.
  81         location[0].id = CORBA::string_dup ("My Location 1");
  82
  83         // "group" is the object group reference.  add_member() may
  84         // change it (TAO's implementation does NOT) so store the new
  85         // reference in the same variable.
  86         group =
  87           load_manager->add_member (group.in (),
  88                                     location,
  89                                     member.in ());
  90
  91    Only one member of a given object group can reside at a given
  92    location.  For example, you cannot add two members of object group
  93    A at "My Location 1".  You can, however, have multiple members of
  94    different object groups residing at the same location.  For
  95    example, a member of object group A and a member of object group B
  96    can reside at "My Location 1".  Also, multiple object group of the
  97    same type, e.g. "IDL:MyObject:1.0", can exist.  In that case,
  98    a member from each object group may reside at the location, despite
  99    the fact they are of the same type.
 100
 101 5. At this point, load balancing will automatically occur once clients
 102    start making invocation via the object group reference.
 103
 104
 105 6. Once you longer have any need of the object group, destroy it as
 106    follows:
 107
 108         load_manager->delete_object (fcid.in ());
 109
 110    "fcid" is the factory creation ID that was returned as an "out"
 111    parameter in the LoadManager::create_object() call.
 112
 113 Approach 2:
 114 Quick, Transparent, Non-Portable and Somewhat Experimental Approach
 115 ...................................................................
 116
 117 Use the "LB_Component" Service Object to transparently add load
 118 balancer support to your dynamically linked servers.  It will
 119 automatically register whatever CORBA objects you want with the load
 120 balancer, and override object reference creation methods such as
 121 _this() and POA::create_reference() so that they return the object
 122 group reference instead of the individual object's reference.  All of
 123 this is done "behind the scenes," meaning that no modification to your
 124 existing code is necessary.
 125
 126 This approach is "experimental" since I'm still tweaking the
 127 configuration interface available to the user, and since I may rename
 128 "LB_Component" to something else like "LB_ServerComponent."  It's
 129 "non-portable" since other ORB's do not use the same dynamic loading
 130 approach the "LB_Component" uses, i.e. ACE's Service Configurator.  It
 131 is, however, portable to all platforms supported by TAO.
 132
 133 Other than that, the underlying group registration mechanisms are
 134 portable since they are straight CORBA calls.  The "LB_Component" just
 135 makes all of the calls on the "LoadManager" for you.
 136
 137 If you want try this approach, try adding the following to your
 138 primary (i.e. the one that creates the object group) server's
 139 `svc.conf' file:
 140
 141   dynamic LB_Component Service_Object * TAO_CosLoadBalancing:_make_TAO_LB_Component() "-LBLocation LOCATION_1 -LBGroup CREATE -LBTypeId IDL:MyObject:1.0"
 142
 143 and the following to your other servers that do NOT create object
 144 groups and simply add themselves to the object group:
 145
 146   dynamic LB_Component Service_Object * TAO_CosLoadBalancing:_make_TAO_LB_Component() "-LBLocation LOCATION_2 -LBGroup file://group.ior -LBTypeId IDL:MyObject:1.0"
 147
 148 etc.  Don't forget to change the location for each object group
 149 member.  With this approach, all of the LoadManager calls I described
 150 in the "standard" approach are handled for you.  Again, this approach
 151 is still really experimental.
 152
 153 If none of this makes sense, you may want to just wait for the
 154 documentation to be completed, and simply use the above "standard"
 155 procedure.
 156
 157
 158 LoadMonitor
 159 ===========
 160 The "LoadMonitor" binary is a stand-alone load monitoring utility.  It
 161 can be used to report loads for the standard load monitor types (CPU,
 162 Disk, Memory and Network), in addition to custom load monitors.
 163 A custom load monitor is used by passing its IOR to the "LoadMonitor"
 164 utility through the "-m" command line option.
 165
 166 Both "PUSH" and "PULL" load monitoring styles may be configured.  The
 167 "PUSH" interval may be configured, as well.
 168
 169 A listing of available "LoadMonitor" command line options is available
 170 by invoking the "LoadMonitor" binary with the "-h" command line
 171 option.
 172
 173 The LoadManager object's IOR must be made available to the
 174 "LoadMonitor" binary.  This can be done using the standard
 175 Interoperable Naming Service "-ORBInitRef" option.  For example, the
 176 following will work if LoadManager IOR is available in the file
 177 `lm.ior'
 178
 179         LoadMonitor -ORBInitRef LoadManager=file://lm.ior