TAO/examples/Load_Balancing/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
  50   struct Member
  51   {
  52     Object obj;
  53     // IOR of an <Object_Group> member.
  54
  55     Member_ID id;
  56     // Each member in an <Object_Group> is identified by a unique ID.
  57   };
  58
  59   typedef string Group_ID;
  60   typedef sequence<Group_ID> Group_List;
  61
  62   // = Forward interface decls.
  63   interface Object_Group;
  64
  65   interface Object_Group_Factory
  66     {
  67       // = TITLE
  68       //   A factory that creates different types of
  69       //   <Object_Group>s and keeps track of them.
  70       //
  71       // = DESCRIPTION
  72       //   Currently, operations for two types of <Object_Group>s are
  73       //   defined: random and round robin.
  74
  75       Object_Group make_round_robin (in Group_ID id)
  76         raises (duplicate_group);
  77       // Creates an <Object_Group> that resolves requests for arbitrary
  78       // members in round robin order.  If an <Object_Group>, of any
  79       // type, with Group_ID <id> has already been created by this
  80       // factory, and hasn't been destroyed, a <duplicate_group>
  81       // exception is thrown.
  82
  83       Object_Group make_random (in Group_ID id)
  84         raises (duplicate_group);
  85       // Creates an <Object_Group> that resolves requests for arbitrary
  86       // members in random order.  If an <Object_Group>, of any
  87       // type, with Group_ID <id> has already been created by this
  88       // factory, and hasn't been destroyed, a <duplicate_group>
  89       // exception is thrown.
  90
  91       Object_Group resolve (in Group_ID id) raises (no_such_group);
  92       // Locates and returns an <Object_Group> by its <Group_ID>.   If
  93       // no <Object_Group> has <Group_ID> of <id>, throw a
  94       // <no_such_group> exception.
  95
  96       Group_List round_robin_groups ();
  97       // Lists all the round robin <Object_Group>s which were created
  98       // by this factory, and haven't been destroyed yet, i.e., return
  99       // a sequence of <Group_ID>s of all existing round robin
 100       // <Object_Group>s created by this factory.
 101
 102       Group_List random_groups ();
 103       // Lists all the random <Object_Group>s which were created
 104       // by this factory, and haven't been destroyed yet, i.e., return
 105       // a sequence of <Group_ID>s of all existing random
 106       // <Object_Group>s created by this factory.
 107     };
 108
 109   interface Object_Group
 110     {
 111       // = TITLE
 112       //   Holds references for 0 or more objects that form an
 113       //   equivalence class, and provides load balancing for those
 114       //   objects.
 115       //
 116       // = DESCRIPTION
 117       //   Whenever a client needs to find an object of a certain type
 118       //   or functionality, it makes a request to the appropriate
 119       //   <Object_Group>.  The <Object_Group> selects one of its
 120       //   members in accordance with the implemented policy (i.e.,
 121       //   random or round robin), and returnd it to the client, thus
 122       //   providing a form of load balancing for its members.
 123       //
 124       readonly attribute string id;
 125       // Each Object Group has its own distinct ID.
 126
 127       void bind (in Member member_) raises (duplicate_member);
 128       // Adds a new <member> to the <Object_Group>.  Note that each
 129       // <Member_ID> in an <Object_Group> must be unique.  If the
 130       // group already contains a member with the same <Member_ID>, a
 131       // <duplicate_member> exceptions is thrown.
 132
 133       void unbind (in Member_ID id) raises (no_such_member);
 134       // Removes a member with the specified <Member_ID> from the
 135       // <Object_Group>.  If none of the group's members have a
 136       // Member_ID of <id>, <no_such_member> exception is thrown.
 137
 138       Object resolve () raises (no_such_member);
 139       // Returns a member object from this <Object_Group> in accordance with
 140       // load balancing policy it implements, i.e., ``random'' or
 141       // ``round robin.''  If the group contains no members, <no_such_member>
 142       // exception is thrown.
 143
 144       Object resolve_with_id (in Member_ID id) raises (no_such_member);
 145       // Returns an object with the specified <Member_ID>.  If this
 146       // <Object_Group> contains no members with the specified
 147       // <Member_ID>, <no_such_member> exception is thrown.
 148
 149       Member_ID_List members ();
 150       // Return a sequence of <Member_ID>s of all of its members.
 151
 152       void destroy ();
 153       // Cleanup the resources associated with this <Object_Group>.
 154       // Subsequent calls to this <Object_Group> should fail, and its
 155       // <id> should become available.  <Object_Group_Factory>
 156       // should no longer list this <Object_Group>.
 157     };
 158 };