TAO/examples/Load_Balancing_persistent/Load_Balancer.idl

   1
   2 //=============================================================================
   3 /**
   4  *  @file    Load_Balancer.idl
   5  *
   6  *  Interfaces for a simple CORBA Load Balancing service, which can
   7  *  be used in conjunction with the Naming Service or alone to
   8  *  improve distributed load balancing.  See README file for a short
   9  *  discussion of other solution approaches for load balancing as
  10  *  well as use cases for this approach.
  11  *
  12  *
  13  *  @author Interfaces in this file came from OrbixNames Load Balancing features with modifications by: Doug Schmidt (d.schmidt@vanderbilt.edu) Marina Spivak (marina@cs.wustl.edu)
  14  */
  15 //=============================================================================
  16
  17
  18 module Load_Balancer
  19 {
  20   // = TITLE
  21   //   Define a module that allows clients to treat a group
  22   //   of <Object>s, i.e., an <Object_Group>, as an equivalence class
  23   //   to improve distributed load balancing.
  24   //
  25   // = DESCRIPTION
  26   //   <Object_Group_Factory> is used to create <Object_Group>s.
  27   //   There are two logical types of <Object_Group>s :
  28   //
  29   //   1. Round Robin <Object_Group> -- This <Object_Group> resolves
  30   //      requests for arbitrary members in round robin order.
  31   //
  32   //   2. Random <Object_Group> -- This <Object_Group> resolves
  33   //      requests for arbitrary members in random order.
  34   //
  35   //   Both types of <Object_Group>s have the same interface (i.e.,
  36   //   <Object_Group>) but different behaviour should be provided
  37   //   in interface implementations appropriately.
  38
  39   // = Module-defined exceptions.
  40   exception no_such_member {};
  41   exception duplicate_member {};
  42   exception duplicate_group {};
  43   exception no_such_group {};
  44
  45   // = Module-defined types.
  46
  47   typedef string Member_ID;
  48   typedef sequence<Member_ID> Member_ID_List;
  49   typedef string Objref;
  50
  51   struct Member
  52   {
  53     Objref obj;
  54     // IOR of an <Object_Group> member.
  55
  56     Member_ID id;
  57     // Each member in an <Object_Group> is identified by a unique ID.
  58   };
  59
  60   typedef string Group_ID;
  61   typedef sequence<Group_ID> Group_List;
  62
  63   // = Forward interface decls.
  64   interface Object_Group;
  65
  66   interface Object_Group_Factory
  67     {
  68       // = TITLE
  69       //   A factory that creates different types of
  70       //   <Object_Group>s and keeps track of them.
  71       //
  72       // = DESCRIPTION
  73       //   Currently, operations for two types of <Object_Group>s are
  74       //   defined: random and round robin.
  75
  76       Object_Group make_round_robin (in Group_ID id)
  77         raises (duplicate_group);
  78       // Creates an <Object_Group> that resolves requests for arbitrary
  79       // members in round robin order.  If an <Object_Group>, of any
  80       // type, with Group_ID <id> has already been created by this
  81       // factory, and hasn't been destroyed, a <duplicate_group>
  82       // exception is thrown.
  83
  84       void unbind_round_robin (in Group_ID id)
  85         raises (no_such_group);
  86       // Unbinds a previous incarnation of the Round Robin if any
  87
  88       Object_Group make_random (in Group_ID id)
  89         raises (duplicate_group);
  90       // Creates an <Object_Group> that resolves requests for arbitrary
  91       // members in random order.  If an <Object_Group>, of any
  92       // type, with Group_ID <id> has already been created by this
  93       // factory, and hasn't been destroyed, a <duplicate_group>
  94       // exception is thrown.
  95
  96       void unbind_random (in Group_ID id)
  97         raises (no_such_group);
  98       // Unbinds a previous incarnation of the Random groups.
  99
 100       Object_Group resolve (in Group_ID id) raises (no_such_group);
 101       // Locates and returns an <Object_Group> by its <Group_ID>.   If
 102       // no <Object_Group> has <Group_ID> of <id>, throw a
 103       // <no_such_group> exception.
 104
 105       Group_List round_robin_groups ();
 106       // Lists all the round robin <Object_Group>s which were created
 107       // by this factory, and haven't been destroyed yet, i.e., return
 108       // a sequence of <Group_ID>s of all existing round robin
 109       // <Object_Group>s created by this factory.
 110
 111       Group_List random_groups ();
 112       // Lists all the random <Object_Group>s which were created
 113       // by this factory, and haven't been destroyed yet, i.e., return
 114       // a sequence of <Group_ID>s of all existing random
 115       // <Object_Group>s created by this factory.
 116     };
 117
 118   interface Object_Group
 119     {
 120       // = TITLE
 121       //   Holds references for 0 or more objects that form an
 122       //   equivalence class, and provides load balancing for those
 123       //   objects.
 124       //
 125       // = DESCRIPTION
 126       //   Whenever a client needs to find an object of a certain type
 127       //   or functionality, it makes a request to the appropriate
 128       //   <Object_Group>.  The <Object_Group> selects one of its
 129       //   members in accordance with the implemented policy (i.e.,
 130       //   random or round robin), and returnd it to the client, thus
 131       //   providing a form of load balancing for its members.
 132       //
 133       readonly attribute string id;
 134       // Each Object Group has its own distinct ID.
 135
 136       void bind (in Member mem) raises (duplicate_member);
 137       // Adds a new <member> to the <Object_Group>.  Note that each
 138       // <Member_ID> in an <Object_Group> must be unique.  If the
 139       // group already contains a member with the same <Member_ID>, a
 140       // <duplicate_member> exceptions is thrown.
 141
 142       void unbind (in Member_ID id) raises (no_such_member);
 143       // Removes a member with the specified <Member_ID> from the
 144       // <Object_Group>.  If none of the group's members have a
 145       // Member_ID of <id>, <no_such_member> exception is thrown.
 146
 147       Objref resolve () raises (no_such_member);
 148       // Returns a member object from this <Object_Group> in accordance with
 149       // load balancing policy it implements, i.e., ``random'' or
 150       // ``round robin.''  If the group contains no members, <no_such_member>
 151       // exception is thrown.
 152
 153       Objref resolve_with_id (in Member_ID id) raises (no_such_member);
 154       // Returns an object with the specified <Member_ID>.  If this
 155       // <Object_Group> contains no members with the specified
 156       // <Member_ID>, <no_such_member> exception is thrown.
 157
 158       Member_ID_List members ();
 159       // Return a sequence of <Member_ID>s of all of its members.
 160
 161       void destroy ();
 162       // Cleanup the resources associated with this <Object_Group>.
 163       // Subsequent calls to this <Object_Group> should fail, and its
 164       // <id> should become available.  <Object_Group_Factory>
 165       // should no longer list this <Object_Group>.
 166     };
 167 };