// -*- C++ -*-
// $Id$

// ============================================================================
//
// = LIBRARY
//   TAO_LoadBalancing
//
// = FILENAME
//    LoadBalancing.idl
//
// = AUTHOR
//    Ossama Othman <ossama@uci.edu>
//
// ============================================================================

#ifndef TAO_LOADBALANCING_IDL
#define TAO_LOADBALANCING_IDL

module LoadBalancing
{
  // = TITLE
  //   This module defines the interfaces and data types used in TAO's
  //   Load Balancing service.

  // = DESCRIPTION
  //     TAO's Load Balancer manages distribution of requests to
  //     replicas of a given Object in an effort to ensure that the
  //     applications/hosts pointed to by the Object reference are as
  //     equally loaded as possible, i.e. load balanced.
  //     The definition of 'load' is application specific, for
  //     example, some applications may choose to load balance access
  //     to multiple dedicated lines, or separate network interfaces,
  //     as well as more traditional load balancing metrics, such as
  //     CPU or disk load.

  interface ReplicaControl
    {
      // = TITLE
      //    An interface that specifies methods the Load Balancer
      //    invokes when informing the ReplicaControl of the
      //    underlying Object's load status.

      // = DESCRIPTION
      //    The ReplicaControl provides a means to control the load on
      //    the Object it is controlling without forcing existing
      //    Objects to change their interface.  The LoadBalancer
      //    issues advisories to the ReplicaControl when it detects
      //    load levels that should be handled in a certain way.

      void high_load_advisory ();
      // When the LoadBalancer detects a "high" load on a given Object
      // via its ReplicaProxy, it issues a high load advisory to the
      // ReplicaControl by invoking this method; typically causing the
      // underlying object to stop accepting requests.

      void nominal_load_advisory ();
      // If a "nominal" load is detected, then a nominal load advisory
      // is issued, typically causing the Object to once again accept
      // requests.
    };

  interface ReplicaProxy
    {
      // = TITLE
      //    This interface provides the methods that the
      //    ReplicaControl object invokes.

      // = DESCRIPTION
      //    The ReplicaProxy resides in the LoadBalancer.
      //    A ReplicaControl object obtains a reference to a
      //    ReplicaProxy from the LoadBalancer, and invokes the
      //    methods in the interface to send load information to the
      //    Load Balancer.

      exception InvalidLoad
        {
          // = TITLE
          //    An invalid load was sent to the ReplicaProxy.
        };

      exception NilControl
        {
          // = TITLE
          //    This exception indicates that a nil ReplicaControl
          //    reference was passed to the ReplicaProxy.
        };

      exception NilReplica
        {
          // = TITLE
          //    This exception indicates that the reference to the
          //    object being load balanced was nil.
        };

      exception NotConnected
        {
          // = TITLE
          //    This exception is thrown when an attempt is made to
          //    disconnect from the LoadBalancer but no connection is
          //    currently established.
        };

      oneway void current_load (in float load);
      // Send current load to the Load Balancer.
      // The application must ensure that all replicas use the same
      // notion of load.

      void disconnect () raises (NotConnected);
      // Disconnect the ReplicaControl from the Load Balancer.  The
      // Object that the ReplicaControl controls will be no longer be
      // load balanced.
    };

  interface LoadBalancer
    {
      // = TITLE
      //    The LoadBalancer interface.

      // = DESCRIPTION
      //    The LoadBalancer distributes incoming requests for a given
      //    Object among several replicas of that Object, thus helping
      //    to ensure that loads are as well balanced across the
      //    systems the replicas are running on as possible.

      exception InvalidReplicaProxy
        {
          // = TITLE
          //    This exception indicates that an attempt was made to
          //    use a ReplicaProxy that is not registered with the
          //    LoadBalancer.
          //    @@ Ossama: where exactly is this exception used?  Who
          //    can raise it!?
        };

      ReplicaProxy connect (in ReplicaControl control,
                            in Object replica)
        raises (ReplicaProxy::NilControl,
                ReplicaProxy::NilReplica);
      // Register ReplicaControl with LoadBalancer, thus allowing the
      // Object to be load balanced.

      Object group_identity ();
      // Return the reference to the object that represents the
      // Replica group being load balanced.  This "group identity"
      // object will cause the client to redirect its requests to a
      // Replica that fits a specific load balancing criteria.
    };

  // @@ Ossama: we may want to add interfaces or operations to access
  // the current list of loads, that would be useful for monitoring
  // applications, and nice GUI-based demos.
  // @@ Ossama: another idea: we have been using this stuff to make
  // all the loads equal, but what if the objective is to keep the
  // load below some value?  Maybe we should provide some callback
  // mechanism to let the application know: the load is too high and
  // there is nothing i can do about it, add more CPUS or reduce the
  // load!
  // Such feedback would be very useful for some applications.
};

#endif /* TAO_LOADBALANCER_IDL */