Broker.idl

Go to the documentation of this file.

/*
 * Broker.idl
 *
 * Copyright (c) 2003 The University of Utah and the Flux Group.
 * All rights reserved.
 *
 * This file is licensed under the terms of the GNU Public License.  
 * See the file "license.terms" for restrictions on redistribution 
 * of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 */

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

#ifndef _broker_idl
#define _broker_idl

/**
 * 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 task manager. */
    interface Manager;

    /**
     * The Task interface encapsulates the per-process resource usage 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
     * @sa RealTimeTaskDelegateImpl
     */
    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);

        /**
         * Method used by the application to report its actual CPU usage.  This
         * method would then be used by adaptation proxies to change the advice
         * parameter to their liking.
         *
         * @param rtt The task object that was actually added to the manager.
         * @param status The CPU usage of the task in microseconds.
         * @param advice The amount of CPU time, in microseconds, that the
         * application would like for the next period.
         *
         * @sa ChangeTaskCPU
         */
        void ReportCPU(in RealTimeTask rtt,
                       in unsigned long status,
                       in unsigned long advice);
    };

    /**
     * A TaskFactory provides an interface for processes to request resource
     * management by a task.
     *
     * @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.
         * @param sp The tasks's scheduling parameters.
         *
         * @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, in ScheduleParameters sp);

        /**
         * 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);

        /**
         * @return The list of task's managed by this policy.
         */
        TaskList GetTaskList();
        
        /**
         * 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, in ScheduleParameters sp)
            raises(DuplicateScheduleParameter,
                   InvalidScheduleParameter,
                   MissingScheduleParameter);

        /** @copydoc Broker::Policy::RemoveTask */
        void RemoveTask(in Task added_task);

        /** @copydoc Broker::Policy::GetTaskList */
        TaskList GetTaskList();

        /**
         * @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);
    };
};

#endif

---