Main Page | Namespace List | Class Hierarchy | Class List | File List | Namespace Members | Class Members | File Members | Related Pages

Broker.idl

Go to the documentation of this file.
00001 /*
00002  * Broker.idl
00003  *
00004  * Copyright (c) 2003, 2004 The University of Utah and the Flux Group.
00005  * All rights reserved.
00006  *
00007  * This file is licensed under the terms of the GNU Public License.  
00008  * See the file "license.terms" for restrictions on redistribution 
00009  * of this file, and for a DISCLAIMER OF ALL WARRANTIES.
00010  */
00011 
00012 /**
00013  * @file Broker.idl
00014  *
00015  * IDL for the CPU Broker.
00016  */
00017 
00018 #ifndef _broker_idl
00019 #define _broker_idl
00020 
00021 /**
00022  * Root name space for the CPU Broker.
00023  */
00024 module Broker
00025 {
00026     /**
00027      * The NamedValue structure is used to construct variable length argument
00028      * lists for some methods.
00029      */
00030     struct NamedValue {
00031         string name;    /**< The symbolic name for the value. */
00032         any value;      /**< The parameter value. */
00033     };
00034 
00035     /**
00036      * Sequence of NamedValue's used when creating a task.
00037      */
00038     typedef sequence<NamedValue> TaskParameters;
00039 
00040     /**
00041      * Sequence of NamedValue's used when beginning a scheduling period.
00042      */
00043     typedef sequence<NamedValue> ScheduleParameters;
00044     
00045     /**
00046      * Sequence of NamedValue's used when making a report.
00047      */
00048     typedef sequence<NamedValue> KeyedReportParameters;
00049 
00050     /**
00051      * Structure used to encode a CPU reservation request.
00052      */
00053     struct CPUReserve {
00054         unsigned long Period;   /**< The period in microseconds. */
00055         unsigned long Compute;  /**< The compute time in microseconds. */
00056     };
00057     
00058     /**
00059      * Exception thrown when an internal error occurs.
00060      */
00061     exception Internal {
00062         string message; /**< A detailed description of the problem. */
00063     };
00064 
00065     /**
00066      * Exception thrown when an invalid parameter is passed in a TaskParameters
00067      * list.
00068      */
00069     exception InvalidTaskParameter {
00070         string message;         /**< A detailed description of the problem. */
00071         NamedValue pair;        /**< The invalid parameter pair. */
00072     };
00073 
00074     /**
00075      * Exception thrown when a required parameter is missing from the
00076      * TaskParameters list.
00077      */
00078     exception MissingTaskParameter {
00079         string name;            /**< The name of the missing parameter. */
00080     };
00081 
00082     /**
00083      * Exception thrown when a duplicate parameter is found in the
00084      * TaskParameters list.
00085      */
00086     exception DuplicateTaskParameter {
00087         string name;            /**< The name of the duplicate parameter. */
00088     };
00089 
00090     /**
00091      * Exception thrown when an invalid parameter is passed in a
00092      * ScheduleParameters list.
00093      */
00094     exception InvalidScheduleParameter {
00095         string message;         /**< A detailed description of the problem. */
00096         NamedValue pair;        /**< The invalid parameter pair. */
00097     };
00098 
00099     /**
00100      * Exception thrown when a required parameter is missing from the
00101      * ScheduleParameters list.
00102      */
00103     exception MissingScheduleParameter {
00104         string name;            /**< The name of the missing parameter. */
00105     };
00106 
00107     /**
00108      * Exception thrown when a duplicate parameter is found in the
00109      * ScheduleParameters list.
00110      */
00111     exception DuplicateScheduleParameter {
00112         string name;            /**< The name of the duplicate parameter. */
00113     };
00114 
00115     /**
00116      * Exception thrown when an action is not valid for an object's current
00117      * state.
00118      */
00119     exception InvalidState {
00120         string message;         /**< A detailed description of the problem. */
00121     };
00122 
00123     /**
00124      * Exception thrown when an invalid status value is received by the
00125      * implementation.
00126      */
00127     exception InvalidStatus {
00128         string message;         /**< A detailed description of the problem. */
00129         unsigned long status;   /**< The invalid status value. */
00130     };
00131 
00132     /* Forward declaration for the overall task manager. */
00133     interface Manager;
00134 
00135     /**
00136      * The Task interface encapsulates the per-process resource usage detection
00137      * policy.
00138      */
00139     interface Task
00140     {
00141         /**
00142          * The name of the task.  Mostly useful for debugging.
00143          */
00144         readonly attribute string Name;
00145 
00146         /**
00147          * Set the manager for this task.
00148          *
00149          * @param man The manager this task was added to.
00150          */
00151         void SetManager(in Manager man);
00152         
00153         /**
00154          * Begin CPU scheduling for this task with the given parameters.
00155          *
00156          * @param sp The high level scheduling parameters.
00157          *
00158          * @exception DuplicateScheduleParameter if the given schedule has a
00159          *            duplicate parameter.
00160          * @exception InvalidScheduleParameter if the given schedule has an
00161          *            invalid parameter.
00162          * @exception MissingScheduleParameter if the given schedule is missing
00163          *            a required parameter.
00164          * @exception CORBA::BAD_INV_ORDER if the method is called without
00165          *            intervening calls to EndCPUScheduling().
00166          */
00167         void BeginCPUScheduling(in ScheduleParameters sp)
00168             raises(DuplicateScheduleParameter,
00169                    InvalidScheduleParameter,
00170                    MissingScheduleParameter);
00171         
00172         /**
00173          * End CPU scheduling for this task.
00174          *
00175          * @exception CORBA::BAD_INV_ORDER if the method is called without
00176          *            BeginCPUScheduling() being called first.
00177          */
00178         void EndCPUScheduling();
00179     };
00180 
00181     /**
00182      * List of tasks.
00183      */
00184     typedef sequence<Task> TaskList;
00185 
00186     /**
00187      * The RealTimeTask interface encapsulates scheduling parameters for tasks
00188      * that have real-time requirements.
00189      *
00190      * @sa RKTask
00191      * @sa RealTimeTaskDelegateImpl
00192      */
00193     interface RealTimeTask : Task
00194     {
00195         /**
00196          * Method used by the application to report its actual CPU usage.  This
00197          * method would then be used by adaptation proxies to change the advice
00198          * parameter to their liking.
00199          *
00200          * @param rtt The task object that was actually added to the manager.
00201          * @param status The CPU usage of the task in microseconds.
00202          * @param advice The amount of CPU time, in microseconds, that the
00203          * application would like for the next period.
00204          * @param krp Non-standard report parameters that are indexed by key
00205          * name.
00206          * @return The actual CPU reserve given to the task.
00207          *
00208          * @sa ChangeTaskCPU
00209          */
00210         CPUReserve PassCPU(in RealTimeTask rtt,
00211                            in CPUReserve status,
00212                            in CPUReserve advice,
00213                            in KeyedReportParameters krp);
00214         
00215         /**
00216          * Method used by the application to report its actual CPU usage.  This
00217          * method would then be used by adaptation proxies to change the advice
00218          * parameter to their liking.
00219          *
00220          * @param status The CPU usage of the task in microseconds.
00221          * @param advice The amount of CPU time, in microseconds, that the
00222          * application would like for the next period.
00223          * @param krp Non-standard report parameters that are indexed by key
00224          * name.
00225          * @return The actual CPU reserve given to the task.
00226          *
00227          * @sa ChangeTaskCPU
00228          */
00229         CPUReserve ReportCPU(in CPUReserve status,
00230                              in CPUReserve advice,
00231                              in KeyedReportParameters krp);
00232     };
00233 
00234     /**
00235      * A TaskFactory provides an interface for processes to request resource
00236      * management by a task.
00237      *
00238      * @sa TaskFactoryTemplate
00239      * @sa ExactTaskFactory
00240      */
00241     interface TaskFactory
00242     {
00243         /**
00244          * Create a new Task object.
00245          *
00246          * @param tp The description of the task.
00247          * @return A new Task object.
00248          *
00249          * @exception DuplicateTaskParameter if the given schedule has a
00250          *            duplicate parameter.
00251          * @exception InvalidTaskParameter if the given schedule has an
00252          *            invalid parameter.
00253          * @exception MissingTaskParameter if the given schedule is missing
00254          *            a required parameter.
00255          */
00256         Task CreateTask(in TaskParameters tp)
00257             raises(DuplicateTaskParameter,
00258                    InvalidTaskParameter,
00259                    MissingTaskParameter);
00260     };
00261 
00262     /**
00263      * A Policy provides an interface for objects that can manage contention
00264      * for a resource.
00265      *
00266      * @sa StrictPolicy
00267      */
00268     interface Policy
00269     {
00270         /**
00271          * The name of the policy.  Mostly useful for debugging.
00272          */
00273         readonly attribute string Name;
00274         
00275         /**
00276          * Add a task to an active policy.  @e NOTE: This method will be called
00277          * @e before the reservation is made, giving the policy a chance to
00278          * adjust any values.
00279          *
00280          * @sa RemoveTask
00281          *
00282          * @param new_task The newly created Task object.
00283          * @param sp The tasks's scheduling parameters.
00284          *
00285          * @exception CORBA::BAD_PARAM if task is nil.
00286          * @exception CORBA::BAD_PARAM if task has already been added.
00287          * @exception CORBA::BAD_INV_ORDER if the method is called without
00288          *            Activate() being called first.
00289          */
00290         void AddTask(in Task new_task, in ScheduleParameters sp)
00291             raises(DuplicateScheduleParameter,
00292                    InvalidScheduleParameter,
00293                    MissingScheduleParameter);
00294 
00295         /**
00296          * Remove a task from an active policy.  @e NOTE: This method will be
00297          * called @e after the reservation has been destroyed, so it can
00298          * safely reallocate the newly freed CPU time.
00299          *
00300          * @sa AddTask
00301          *
00302          * @param added_task The task to remove.
00303          *
00304          * @exception CORBA::BAD_PARAM if task is nil.
00305          * @exception CORBA::BAD_PARAM if task has already been removed.
00306          * @exception CORBA::BAD_INV_ORDER if the method is called without
00307          *            Activate() being called first.
00308          */
00309         void RemoveTask(in Task added_task);
00310 
00311         /**
00312          * @return The list of task's managed by this policy.
00313          */
00314         TaskList GetTaskList();
00315         
00316         /**
00317          * Activate the policy.  @e NOTE: The policy is expected to discover
00318          * and adjust the scheduling parameters of any currently executing
00319          * tasks.
00320          *
00321          * @sa Deactivate
00322          *
00323          * @param tasks The list of tasks the policy needs to manage.
00324          *
00325          * @exception CORBA::BAD_INV_ORDER if the method is called without
00326          *            intervening calls to Deactivate().
00327          */
00328         void Activate(in TaskList tasks);
00329 
00330         /**
00331          * Deactivate an active policy.  @e NOTE: The policy should @e change
00332          * any scheduling parameters of the currently executing tasks, the
00333          * next policy to be activated will handle any changes.
00334          *
00335          * @sa Deactivate
00336          *
00337          * @exception CORBA::BAD_INV_ORDER if the method is called on an
00338          *            inactive policy.
00339          */
00340         void Deactivate();
00341 
00342         /**
00343          * @param task The Task object requesting a CPU time change.
00344          * @param advice The CPU time advice from the Task object.
00345          * @return The actual CPU reserve given to the task.
00346          */
00347         CPUReserve ChangeTaskCPU(in RealTimeTask task, in CPUReserve advice)
00348             raises(InvalidState);
00349         
00350         /**
00351          * @return The maximum percentage of CPU that can be allocated to all
00352          * of the tasks.
00353          */
00354         float GetMaxCPUAllocation();
00355 
00356         /**
00357          * @param amount The maximum percentage of CPU that can be allocated to
00358          * all of the tasks.
00359          */
00360         void SetMaxCPUAllocation(in float amount);
00361 
00362         /**
00363          * The minimum value that can be passed to SetMaxCPUAllocation.
00364          */
00365         const float CPU_ALLOCATION_MIN = 0.01;
00366 
00367         /**
00368          * The maximum value that can be passed to SetMaxCPUAllocation.
00369          */
00370         const float CPU_ALLOCATION_MAX = 0.99;
00371     };
00372 
00373     /**
00374      * The Manager interface is a point of indirection for the Tasks that wish
00375      * to be scheduled by a contention policy.
00376      *
00377      * @sa ManagerImpl
00378      */
00379     interface Manager
00380     {
00381         /**
00382          * The current policy to use when handling CPU time change requests.
00383          * If this value is nil, the manager will implement a straightforward
00384          * default policy.
00385          */
00386         attribute Policy CurrentPolicy;
00387 
00388         /** @copydoc Broker::Policy::AddTask */
00389         void AddTask(in Task new_task, in ScheduleParameters sp)
00390             raises(DuplicateScheduleParameter,
00391                    InvalidScheduleParameter,
00392                    MissingScheduleParameter);
00393 
00394         /** @copydoc Broker::Policy::RemoveTask */
00395         void RemoveTask(in Task added_task);
00396 
00397         /** @copydoc Broker::Policy::GetTaskList */
00398         TaskList GetTaskList();
00399 
00400         /**
00401          * @copydoc Broker::Policy::ChangeTaskCPU
00402          *
00403          * Note: If there is no policy set, the manager will simply call
00404          * SetComputeTime() on the given task with the given advice.
00405          */
00406         CPUReserve ChangeTaskCPU(in RealTimeTask task, in CPUReserve advice)
00407             raises(InvalidState);
00408     };
00409 };
00410 
00411 #endif

Generated on Tue Jun 22 14:50:08 2004 for CPU Broker by doxygen 1.3.6