/**
 * @file Federated_Test.idl
 *
 * $Id$
 *
 * @author Carlos O'Ryan <coryan@uci.edu>
 *
 */

#include "tao/ULongLongSeq.pidl"

module Federated_Test
{
  interface Peer;

  interface Loopback;

  /**
   * @interface Coordinator
   *
   * @brief Controls a federated test.
   *
   * Implementations of the Control interface:
   *
   * -# wait for all the peers to join
   * -# connecting the peers to each other
   * -# run different experiments on each peer
   * -# collect the results and print them
   *
   */
  interface Control
  {
    /// Join a new peer into the simulation.
    /**
     * Implementations of this interface arbitrarly decide when there
     * are "enough" peers to run the test.
     */
    void join (in Peer the_peer);
  };

  /// The results of a single experiment
  typedef CORBA::ULongLongSeq Experiment_Results;

  /**
   * @interface Peer
   *
   * @brief A member of a federated test
   *
   * Peers define the required interface to participate in a federated
   * test.
   */
  interface Peer
  {
    /// Shutdown the peer
    void shutdown ();

    /// Setup an Consumer/Supplier loopback pair
    /**
     * Some experiments require one or more peers to setup a
     * "loopback" through their event channel, i.e. a
     * Consumer/Supplier pair that simply "loop" every event they
     * receive through the event channel.
     *
     * @param experiment_id Each experiment receives a unique ID to
     * separate resources.
     *
     * @param base_event_type The type the Consumer part of the
     * loopback should subscribe to, the supplier generate events of
     * type base_event_type + 1
     *
     * @return The returned object can be used to disconnect and
     * destroy the loopback elements.
     */
    Loopback setup_loopback (in long experiment_id,
                             in long base_event_type);

    /// Run a single experiment
    /**
     * @param experiment_id Each experiment is assigned a different ID
     * by the Control object.
     * @param iterations How many iterations of the experiment should
     * be run.
     *
     * @return All the samples captured in the experiment, the samples
     * are returned in microseconds.
     */
    Experiment_Results run_experiment (in long experiment_id,
                                       in long iterations);

    /// Return the event channel in this peer
    readonly attribute Object channel;

    /// Connect to a remote peer
    void connect (in Peer remote_peer);
  };

  /**
   * @interface Loopback
   *
   * @brief Control the elements on a Consumer/Supplier loopback pair.
   */
  interface Loopback
  {
    /// Disconnect and destroy the loopback elements
    void disconnect ();
  };
};