Broker.idl

Go to the documentation of this file.

/**
 * @file Broker.idl
 *
 * IDL for the CPU Broker.
 */

/**
 * Root name space for the CPU Broker.
 */
module Broker
{
    /**
     * The NamedValue structure is used to construct variable length argument
     * lists for some methods.
     */
    struct NamedValue {
        string name;    /**< The symbolic name for the value. */
        any value;      /**< The parameter value. */
    };

    /**
     * Sequence of NamedValue's used when creating a task.
     */
    typedef sequence<NamedValue> TaskParameters;

    /**
     * Sequence of NamedValue's used when beginning a scheduling period.
     */
    typedef sequence<NamedValue> ScheduleParameters;
    
    /**
     * Exception thrown when an internal error occurs.
     */
    exception Internal {
        string message; /**< A detailed description of the problem. */
    };

    /**
     * Exception thrown when an invalid parameter is passed in a TaskParameters
     * list.
     */
    exception InvalidTaskParameter {
        string message;         /**< A detailed description of the problem. */
        NamedValue pair;        /**< The invalid parameter pair. */
    };

    /**
     * Exception thrown when a required parameter is missing from the
     * TaskParameters list.
     */
    exception MissingTaskParameter {
        string name;            /**< The name of the missing parameter. */
    };

    /**
     * Exception thrown when a duplicate parameter is found in the
     * TaskParameters list.
     */
    exception DuplicateTaskParameter {
        string name;            /**< The name of the duplicate parameter. */
    };

    /**
     * Exception thrown when an invalid parameter is passed in a
     * ScheduleParameters list.
     */
    exception InvalidScheduleParameter {
        string message;         /**< A detailed description of the problem. */
        NamedValue pair;        /**< The invalid parameter pair. */
    };

    /**
     * Exception thrown when a required parameter is missing from the
     * ScheduleParameters list.
     */
    exception MissingScheduleParameter {
        string name;            /**< The name of the missing parameter. */
    };

    /**
     * Exception thrown when a duplicate parameter is found in the
     * ScheduleParameters list.
     */
    exception DuplicateScheduleParameter {
        string name;            /**< The name of the duplicate parameter. */
    };

    /**
     * XXX fill me in.
     */
    exception InvalidState {
        string message;         /**< A detailed description of the problem. */
    };

    /**
     * Exception thrown when an invalid status value is received by the
     * implementation.
     */
    exception InvalidStatus {
        string message;         /**< A detailed description of the problem. */
        unsigned long status;   /**< The invalid status value. */
    };

    /* Forward declaration for the overall manager. */
    interface Manager;

    /**
     * The Task interface encapsulates the per-process detection policy.
     */
    interface Task
    {
        /**
         * The name of the task.  Mostly useful for debugging.
         */
        readonly attribute string Name;

        /**
         * Begin CPU scheduling for this task with the given parameters.
         *
         * @param man The resource manager that will handle scheduling
         *            during contention.
         * @param cs The high level scheduling parameters.
         *
         * @exception DuplicateScheduleParameter if the given schedule has a
         *            duplicate parameter.
         * @exception InvalidScheduleParameter if the given schedule has an
         *            invalid parameter.
         * @exception MissingScheduleParameter if the given schedule is missing
         *            a required parameter.
         * @exception CORBA::BAD_INV_ORDER if the method is called without
         *            intervening calls to EndCPUScheduling().
         */
        void BeginCPUScheduling(in Manager man, in ScheduleParameters cs)
            raises(DuplicateScheduleParameter,
                   InvalidScheduleParameter,
                   MissingScheduleParameter);

        /**
         * End CPU scheduling for this task.
         *
         * @exception CORBA::BAD_INV_ORDER if the method is called without
         *            BeginCPUScheduling() being called first.
         */
        void EndCPUScheduling();
    };

    /**
     * List of tasks.
     */
    typedef sequence<Task> TaskList;

    /**
     * The RealTimeTask interface encapsulates scheduling parameters for tasks
     * that have real-time requirements.
     *
     * @sa RKTask
     */
    interface RealTimeTask : Task
    {
        /**
         * The period, in microseconds.
         */
        readonly attribute unsigned long Period;

        /**
         * The deadline, in microseconds, relative to the start of the period.
         */
        readonly attribute unsigned long Deadline;
        
        /**
         * @return The number of microseconds of compute time.
         */
        unsigned long GetComputeTime();

        /**
         * @param usecs The number of microseconds of compute time.
         */
        void SetComputeTime(in unsigned long usecs);
    };

    /**
     * A RealTimeAdvocate provides an interface for objects that will adapt a
     * RealTimeTask's scheduling parameters based on whether or not the task
     * is meeting its deadlines.
     *
     * @sa ExactTaskAdvocate
     */
    interface RealTimeAdvocate : RealTimeTask
    {
        /**
         * Report the application's status to the CPU Broker.
         *
         * @param status XXX
         *
         * @exception InvalidStatus if the status value is invalid.
         * @exception CORBA::BAD_INV_ORDER if the method is called without
         *            BeginCPUScheduling() being called first.
         */
        void ReportCPU(in unsigned long status)
            raises(InvalidStatus);
    };

    /**
     * A TaskFactory provides an interface for processes to request resource
     * management by an advocate.
     *
     * @sa TaskFactoryTemplate
     * @sa ExactTaskFactory
     */
    interface TaskFactory
    {
        /**
         * Create a new Task object.
         *
         * @param tp The description of the task.
         * @return A new Task object.
         *
         * @exception DuplicateTaskParameter if the given schedule has a
         *            duplicate parameter.
         * @exception InvalidTaskParameter if the given schedule has an
         *            invalid parameter.
         * @exception MissingTaskParameter if the given schedule is missing
         *            a required parameter.
         */
        Task CreateTask(in TaskParameters tp)
            raises(DuplicateTaskParameter,
                   InvalidTaskParameter,
                   MissingTaskParameter);
    };

    /**
     * A Policy provides an interface for objects that can manage contention
     * for a resource.
     *
     * @sa StrictPolicy
     */
    interface Policy
    {
        /**
         * The name of the policy.  Mostly useful for debugging.
         */
        readonly attribute string Name;
        
        /**
         * Add a task to an active policy.  @e NOTE: This method will be called
         * @e before the reservation is made, giving the policy a chance to
         * adjust any values.
         *
         * @sa RemoveTask
         *
         * @param new_task The newly created Task object.
         *
         * @exception CORBA::BAD_PARAM if task is nil.
         * @exception CORBA::BAD_PARAM if task has already been added.
         * @exception CORBA::BAD_INV_ORDER if the method is called without
         *            Activate() being called first.
         */
        void AddTask(in Task new_task);

        /**
         * Remove a task from an active policy.  @e NOTE: This method will be
         * called @e after the reservation has been destroyed, so it can
         * safely reallocate the newly freed CPU time.
         *
         * @sa AddTask
         *
         * @param added_task The task to remove.
         *
         * @exception CORBA::BAD_PARAM if task is nil.
         * @exception CORBA::BAD_PARAM if task has already been removed.
         * @exception CORBA::BAD_INV_ORDER if the method is called without
         *            Activate() being called first.
         */
        void RemoveTask(in Task added_task);

        /**
         * Activate the policy.  @e NOTE: The policy is expected to discover
         * and adjust the scheduling parameters of any currently executing
         * tasks.
         *
         * @sa Deactivate
         *
         * @param tasks The list of tasks the policy needs to manage.
         *
         * @exception CORBA::BAD_INV_ORDER if the method is called without
         *            intervening calls to Deactivate().
         */
        void Activate(in TaskList tasks);

        /**
         * Deactivate an active policy.  @e NOTE: The policy should @e change
         * any scheduling parameters of the currently executing tasks, the
         * next policy to be activated will handle any changes.
         *
         * @sa Deactivate
         *
         * @exception CORBA::BAD_INV_ORDER if the method is called on an
         *            inactive policy.
         */
        void Deactivate();

        /**
         * @param task The Task object requesting a CPU time change.
         * @param ct The Task's current CPU time.
         * @param status The status value reported by Task.ReportCPU().
         * @param advice The CPU time advice from the Task object.
         */
        void ChangeTaskCPU(in RealTimeTask task,
                           in unsigned long ct,
                           in unsigned long status,
                           in unsigned long advice)
            raises(InvalidState);
    };

    /**
     * The Manager interface is a point of indirection for the Tasks that wish
     * to be scheduled by a contention policy.
     *
     * @sa ManagerImpl
     */
    interface Manager
    {
        /**
         * The current policy to use when handling CPU time change requests.
         * If this value is nil, the manager will implement a straightforward
         * default policy.
         */
        attribute Policy CurrentPolicy;

        /** @copydoc Broker::Policy::AddTask */
        void AddTask(in Task new_task);

        /** @copydoc Broker::Policy::RemoveTask */
        void RemoveTask(in Task added_task);
        
        /**
         * @copydoc Broker::Policy::ChangeTaskCPU
         *
         * Note: If there is no policy set, the manager will simply call
         * SetComputeTime() on the given task with the given advice.
         */
        void ChangeTaskCPU(in RealTimeTask task,
                           in unsigned long ct,
                           in unsigned long status,
                           in unsigned long advice)
            raises(InvalidState);
    };
};

---