path: root/TAO/orbsvcs/orbsvcs/RtecScheduler.idl

// $Id$

#include "CosTimeBase.idl"

module RtecScheduler
{
  // Module TimeBase defines the OMG Time Service.
  typedef TimeBase::TimeT Time; // 100 nanoseconds
  typedef Time Quantum;

  typedef long Period; // 100 nanoseconds

  enum Criticality
  // Defines the criticality of the operation.
  // For use with Dynamic Scheduler.
  {
    VERY_LOW_CRITICALITY,
    LOW_CRITICALITY,
    MEDIUM_CRITICALITY,
    HIGH_CRITICALITY,
    VERY_HIGH_CRITICALITY
  };

  enum Importance
  // Defines the importance of the operation,
  // which can be used by the Scheduler as a
  // "tie-breaker" when other scheduling
  // parameters are equal.
  {
    VERY_LOW_IMPORTANCE,
    LOW_IMPORTANCE,
    MEDIUM_IMPORTANCE,
    HIGH_IMPORTANCE,
    VERY_HIGH_IMPORTANCE
  };

  enum Info_Type
  // Defines type of operation information.
  {
    OPERATION,
    CONJUNCTION,
    DISJUNCTION
  };

  enum Dependency_Type
  // Specify one-way or two-way call.
  {
    ONE_WAY_CALL,
    TWO_WAY_CALL
  };

  typedef long handle_t;
  // RT_Info's are assigned per-application
  // unique identifiers.

  struct Dependency_Info
  {
    Dependency_Type dependency_type;
    long number_of_calls;
    handle_t rt_info;
    // Notice the reference to the RT_Info we
    // depend on.
  };

  typedef sequence<Dependency_Info> Dependency_Set;

  typedef long OS_Priority;
  typedef long Preemption_Subpriority;
  typedef long Preemption_Priority;

  struct RT_Info
    // = TITLE
    //   Describes the QoS for an "RT_Operation".
    //
    // = DESCRIPTION
    // The CPU requirements and QoS for each
    // "entity" implementing an application
    // operation is described by the following
    // information.
  {
    // Application-defined string that uniquely
    // identifies the operation.
    string entry_point;

    // The scheduler-defined unique identifier.
    handle_t handle;

    // Execution times.
    Time worst_case_execution_time;
    Time typical_execution_time;

    // To account for server data caching.
    Time cached_execution_time;

    // For rate-base operations, this expresses
    // the rate.  0 means "completely pasive",
    // i.e., this operation only executes when
    // called.
    Period period;

    // Operation Criticality (user assigned significance).
    Criticality criticality;

    // Operation importance, used to "break ties".
    Importance importance;

    // For time-slicing (for BACKGROUND operations only).
    Quantum quantum;

    // The number of internal threads contained by
    // the operation.
    long threads;

    // The following attributes are defined by
    // the Scheduler once the off-line schedule
    // is computed.

    // The operations we depend upon.
    Dependency_Set dependencies;

    // The OS thread priority for processing the 
    // events generated from this RT_Info.
    OS_Priority priority;


    // For ordering RT_Info's with equal priority.
    Preemption_Subpriority preemption_subpriority;

    // The queue number for this RT_Info.
    Preemption_Priority preemption_priority;

    // Info_Type
    Info_Type info_type;

    // Token reserved for the scheduler's internal use:
    // information placed here from outside the scheduler
    // implementation is prone to be overwritten.
    unsigned long volatile_token;
  };

  exception DUPLICATE_NAME {};
  // The application is trying to register the same task again.

  exception UNKNOWN_TASK {};
  // The RT_Info handle was not valid.

  exception NOT_SCHEDULED {};
  // The application is trying to obtain scheduling information, but
  // none is available.

  exception UTILIZATION_BOUND_EXCEEDED {};
  exception INSUFFICIENT_THREAD_PRIORITY_LEVELS {};
  exception TASK_COUNT_MISMATCH {};
  // Problems while computing off-line scheduling.

  typedef sequence<RT_Info> RT_Info_Set;

  // TODO: Find a reasonable name for this interface, maybe we should
  // change the name of the module to RtecSchedulerAdmin and name this
  // Scheduler
  interface Scheduler
    // = DESCRIPTION
    //   This class holds all the RT_Info's for a single application.
    //   During the configuration run this will be implemented as a
    //   single remote object, whose services are used by the
    //   suppliers, consumers and the EC.
    //   At run-time each process will hold a copy of the compiled
    //   version of the Scheduler, using the precomputed data to
    //   resolve requests (avoiding any remote calls) and ignoring any
    //   requests for modifying its state.
    //   A Factory class will be used to choose the proper
    //   implementation.
    //
    //   This class must be registered with the naming service using a
    //   well known name ("Scheduler" seems the obvious choice), the
    //   Naming Context will account for different applications and
    //   modes.
    //
    //   Once the scheduling data is computed it can be retrieved
    //   remotely to generate the code for the run-time version.
  {
    handle_t create (in string entry_point) raises (DUPLICATE_NAME);
    // Creates a new RT_Info entry for the function identifier
    // "entry_point", it can be any string, but the fully qualified
    // name function name is suggested.
    // Returns a handle to the RT_Info.

    handle_t lookup (in string entry_point);
    // Lookups a handle for entry_point.
    // TODO: Should we add INVALID_HANDLE or raise an exception?

    RT_Info get (in handle_t handle) raises (UNKNOWN_TASK);
    // Retrieve information about an RT_Info.

    void set (in handle_t handle,
              in Criticality criticality,
              in Time time,
              in Time typical_time,
              in Time cached_time,
              in Period period,
              in Importance importance,
              in Quantum quantum,
              in long threads,
              in Info_Type info_type)
      raises (UNKNOWN_TASK);
    // Set the attributes of an RT_Info.
    // Notice that some values may not be modified (like priority).
    // Criticality and Info_Type are only used with the Dynamic Scheduler.

    void add_dependency (in handle_t handle,
                         in handle_t dependency,
                         in long number_of_calls,
                         in Dependency_Type dependency_type)
      raises (UNKNOWN_TASK);
    // Adds <dependency> to <handle>.
    // Dependency_Type is only used with the Dynamic Scheduler.

    void priority (in handle_t handle,
                       out OS_Priority priority,
                       out Preemption_Subpriority p_subpriority,
                       out Preemption_Priority p_priority)
      raises (UNKNOWN_TASK, NOT_SCHEDULED);
    void entry_point_priority (in string entry_point,
                               out OS_Priority priority,
                               out Preemption_Subpriority p_subpriority,
                               out Preemption_Priority p_priority)
      raises (UNKNOWN_TASK, NOT_SCHEDULED);
    // Obtain the run time priorities.
    // TODO: Do we need the two interfaces or is it simply confusing?
    // If we should to keep only the <handle> version: Are the extra
    // round-trips too expensive?
    // If we choose only the <entry_point> version: Are the copies for
    // the string affordable?

    void compute_scheduling (in long minimum_priority,
                             in long maximum_priority,
                             out RT_Info_Set infos)
      raises (UTILIZATION_BOUND_EXCEEDED,
              INSUFFICIENT_THREAD_PRIORITY_LEVELS,
              TASK_COUNT_MISMATCH);
    // Computes the scheduling priorities, returns the RT_Info's with
    // their priorities properly filled.
    // This info can be cached by a Run_Time_Scheduler service or
    // dumped into a C++ file for compilation and even faster (static)
    // lookup.

    // TODO: The dependencies field can be removed from the RT_Info
    // and made part of the secrets of "Application", adding the
    // following to satisfy curious clients:
    //
    // struct Dependency {
    //   long number_of_calls;
    //   Dependency_Type dependency_type;
    //   handle_t dependency;
    // };
    // typedef sequence<Dependency> Dependency_Set;
    //
    // Dependency_Set dependencies (in handle_t handle)
    //    raises (UNKNOWN_TASK);
    // Returns the list of dependencies
    //
    // long number_of_dependencies (in handle_t handle)
    //    raises (UNKNOWN_TASK);
    // Returns the number of dependencies.

  };
};