Broker.idl

Go to the documentation of this file.

/*
 * Broker.idl
 *
 * Copyright (c) 2003, 2004 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;
    
    /**
     * Sequence of NamedValue's used when making a report.
     */
    typedef sequence<NamedValue> KeyedReportParameters;

    /**
     * Structure used to encode a CPU reservation request.
     */
    struct CPUReserve {
        unsigned long Period;   /**< The period in microseconds. */
        unsigned long Compute;  /**< The compute time in microseconds. */
    };
    
    /**
     * 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. */
    };

    /**
     * Exception thrown when an action is not valid for an object's current
     * state.
     */
    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;

        /**
         * Set the manager for this task.
         *
         * @param man The manager this task was added to.
         */
        void SetManager(in Manager man);
        
        /**
         * Begin CPU scheduling for this task with the given parameters.
         *
         * @param sp 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 ScheduleParameters sp)
            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
    {
        /**
         * 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.
         * @param krp Non-standard report parameters that are indexed by key
         * name.
         * @return The actual CPU reserve given to the task.
         *
         * @sa ChangeTaskCPU
         */
        CPUReserve PassCPU(in RealTimeTask rtt,
                           in CPUReserve status,
                           in CPUReserve advice,
                           in KeyedReportParameters krp);
        
        /**
         * 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 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.
         * @param krp Non-standard report parameters that are indexed by key
         * name.
         * @return The actual CPU reserve given to the task.
         *
         * @sa ChangeTaskCPU
         */
        CPUReserve ReportCPU(in CPUReserve status,
                             in CPUReserve advice,
                             in KeyedReportParameters krp);
    };

    /**
     * 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)
            raises(DuplicateScheduleParameter,
                   InvalidScheduleParameter,
                   MissingScheduleParameter);

        /**
         * 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 advice The CPU time advice from the Task object.
         * @return The actual CPU reserve given to the task.
         */
        CPUReserve ChangeTaskCPU(in RealTimeTask task, in CPUReserve advice)
            raises(InvalidState);
        
        /**
         * @return The maximum percentage of CPU that can be allocated to all
         * of the tasks.
         */
        float GetMaxCPUAllocation();

        /**
         * @param amount The maximum percentage of CPU that can be allocated to
         * all of the tasks.
         */
        void SetMaxCPUAllocation(in float amount);

        /**
         * The minimum value that can be passed to SetMaxCPUAllocation.
         */
        const float CPU_ALLOCATION_MIN = 0.01;

        /**
         * The maximum value that can be passed to SetMaxCPUAllocation.
         */
        const float CPU_ALLOCATION_MAX = 0.99;
    };

    /**
     * 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.
         */
        CPUReserve ChangeTaskCPU(in RealTimeTask task, in CPUReserve advice)
            raises(InvalidState);
    };
};

#endif

---