diff options
Diffstat (limited to 'TAO/orbsvcs/orbsvcs/Sched/DynSched.h')
| -rw-r--r-- | TAO/orbsvcs/orbsvcs/Sched/DynSched.h | 305 |
1 files changed, 159 insertions, 146 deletions
diff --git a/TAO/orbsvcs/orbsvcs/Sched/DynSched.h b/TAO/orbsvcs/orbsvcs/Sched/DynSched.h index cbb6c142f56..221d8a58dee 100644 --- a/TAO/orbsvcs/orbsvcs/Sched/DynSched.h +++ b/TAO/orbsvcs/orbsvcs/Sched/DynSched.h @@ -1,22 +1,17 @@ // -*- C++ -*- -// $Id$ -// -// ============================================================================ -// -// = LIBRARY -// sched -// -// = FILENAME -// DynSched.h -// -// = CREATION DATE -// 23 January 1997 -// -// = AUTHOR -// Chris Gill -// -// ============================================================================ +//============================================================================= +/** + * @file DynSched.h + * + * $Id$ + * + * $Id$ + * + * @author Chris Gill + */ +//============================================================================= + #ifndef DYNSCHED_H #define DYNSCHED_H @@ -38,14 +33,16 @@ TAO_BEGIN_VERSIONED_NAMESPACE_DECL +/** + * @class ACE_DynScheduler + * + * @brief Dispatch scheduling interface. + * + * This abstract base class provides the majority of the + * implementation of either an off-line scheduler, or the + * necessary on-line component of the Scheduler. + */ class TAO_RTSched_Export ACE_DynScheduler - // = TITLE - // Dispatch scheduling interface. - // - // = DESCRIPTION - // This abstract base class provides the majority of the - // implementation of either an off-line scheduler, or the - // necessary on-line component of the Scheduler. { public: @@ -74,8 +71,8 @@ public: typedef ACE_Map_Iterator <ACE_CString, RT_Info *, ACE_Null_Mutex> Thread_Map_Iterator; + /// Objects are named by unique strings. typedef const char *Object_Name; - // Objects are named by unique strings. enum status_t { // The following are used both by the runtime Scheduler and during @@ -119,8 +116,8 @@ public: // public member functions // ///////////////////////////// + /// public dtor virtual ~ACE_DynScheduler (); - // public dtor // = Utility function for outputting the textual // representation of a status_t value. @@ -136,89 +133,99 @@ public: // = Initialize the scheduler. + /** + * The minimum and maximum priority are the OS-specific priorities that + * are used when creating the schedule (assigning priorities). The + * minimum_priority is the priority value of the lowest priority. + * It may be numerically higher than the maximum_priority, on OS's such + * as VxWorks that use lower values to indicate higher priorities. + * + * When Scheduler::schedule is called, the schedule is output to the + * file named by "runtime_filename" if it is non-zero. + * This file is compilable; it is linked into the runtime executable + * to provide priorities to the runtime scheduling component. + * If the "rt_info_filename" is non-zero, the RT_Info for + * every task is exported to it. It is not used at runtime. + * If the "timeline_filename" is non-zero, the timeline output + * file is created. It is not used at runtime. + * + * The runtime scheduling component ignores these filenames. It just + * uses the priorities that were linked in to the executable, after + * converting them to platform-specific values. + */ void init (const OS_Priority minimum_priority, const OS_Priority maximum_priority, const char *runtime_filename = 0, const char *rt_info_filename = 0, const char *timeline_filename = 0); - // The minimum and maximum priority are the OS-specific priorities that - // are used when creating the schedule (assigning priorities). The - // minimum_priority is the priority value of the lowest priority. - // It may be numerically higher than the maximum_priority, on OS's such - // as VxWorks that use lower values to indicate higher priorities. - // - // When Scheduler::schedule is called, the schedule is output to the - // file named by "runtime_filename" if it is non-zero. - // This file is compilable; it is linked into the runtime executable - // to provide priorities to the runtime scheduling component. - // If the "rt_info_filename" is non-zero, the RT_Info for - // every task is exported to it. It is not used at runtime. - // If the "timeline_filename" is non-zero, the timeline output - // file is created. It is not used at runtime. - // - // The runtime scheduling component ignores these filenames. It just - // uses the priorities that were linked in to the executable, after - // converting them to platform-specific values. + /** + * Prepare for another schedule computation: once a reasonable schedule + * has been generated, a new schedule will not be computed unless an + * RT_Info is added, or this method is invoked to clear the previous + * schedule (allows fault correcting alteration of RT_Infos outside the + * scheduler implementation, followed by generation of a new schedule). + */ void reset (); - // Prepare for another schedule computation: once a reasonable schedule - // has been generated, a new schedule will not be computed unless an - // RT_Info is added, or this method is invoked to clear the previous - // schedule (allows fault correcting alteration of RT_Infos outside the - // scheduler implementation, followed by generation of a new schedule). // = Registers a task. + /** + * If the Task registration succeeds, this function returns SUCCEEDED + * and sets "handle" to a unique identifier for the task. + * Otherwise, it returns either VIRTUAL_MEMORY_EXHAUSTED or + * TASK_ALREADY_REGISTERED sets the handle to 0. (A task may + * only be registered once.) + */ status_t register_task (RT_Info *, handle_t &handle); - // If the Task registration succeeds, this function returns SUCCEEDED - // and sets "handle" to a unique identifier for the task. - // Otherwise, it returns either VIRTUAL_MEMORY_EXHAUSTED or - // TASK_ALREADY_REGISTERED sets the handle to 0. (A task may - // only be registered once.) + /** + * Tries to find the RT_Info corresponding to <name> in the RT_Info + * database. Returns SUCCEEDED if <name> was found and <rtinfo> was + * set. Returns UNKNOWN_TASK if <name> was not found, but <rtinfo> + * was set to a newly allocated RT_Info. In this UNKNOWN_TASK case, + * the task must call RT_Info::set to fill in execution properties. + * In the SUCCEEDED and UNKNOWN_TASK cases, this->register_task + * (rtinfo, 0, handle) is called. Returns FAILED if an error + * occurs. + * + * One motivation for allocating RT_Info's from within the Scheduler + * is to allow RT_Infos to persist after the tasks that use them. + * For instance, we may want to call this->schedule right before the + * application exits a configuration run. If the tasks have been + * deleted (deleting their RT_Infos with them), this->schedule will + * fail. + */ status_t get_rt_info (Object_Name name, RT_Info* &rtinfo); - // Tries to find the RT_Info corresponding to <name> in the RT_Info - // database. Returns SUCCEEDED if <name> was found and <rtinfo> was - // set. Returns UNKNOWN_TASK if <name> was not found, but <rtinfo> - // was set to a newly allocated RT_Info. In this UNKNOWN_TASK case, - // the task must call RT_Info::set to fill in execution properties. - // In the SUCCEEDED and UNKNOWN_TASK cases, this->register_task - // (rtinfo, 0, handle) is called. Returns FAILED if an error - // occurs. - // - // One motivation for allocating RT_Info's from within the Scheduler - // is to allow RT_Infos to persist after the tasks that use them. - // For instance, we may want to call this->schedule right before the - // application exits a configuration run. If the tasks have been - // deleted (deleting their RT_Infos with them), this->schedule will - // fail. + /// Obtains an RT_Info based on its "handle". status_t lookup_rt_info (handle_t handle, RT_Info* &rtinfo); - // Obtains an RT_Info based on its "handle". + /// Obtains a Config_Info based on its priority. status_t lookup_config_info (Preemption_Priority priority, Config_Info* &config_info); - // Obtains a Config_Info based on its priority. + /// This sets up the data structures, invokes the internal scheduling method. status_t schedule (ACE_Unbounded_Set<Scheduling_Anomaly *> &anomaly_set); - // This sets up the data structures, invokes the internal scheduling method. + /// this prints the entire set of timeline outputs to the specified file status_t output_timeline (const char *filename, const char *heading); - // this prints the entire set of timeline outputs to the specified file // = Access a thread priority. + /** + * "priority" is the OS thread priority that was assigned to the Task that + * was assigned "handle". "subpriority" combines the dynamic and static + * subpriorities of the Task that was assigned handle. "preemption_prio" + * is a platform-independent priority queue number, ranging from a + * highest priority value of 0 to the lowest priority value, which is + * returned by "minimum_priority_queue ()". Returns 0 on success, + * or -1 if an invalid handle was supplied. + */ virtual int priority (const handle_t handle, OS_Priority &priority, Sub_Priority &subpriority, Preemption_Priority &preemption_prio); - // "priority" is the OS thread priority that was assigned to the Task that - // was assigned "handle". "subpriority" combines the dynamic and static - // subpriorities of the Task that was assigned handle. "preemption_prio" - // is a platform-independent priority queue number, ranging from a - // highest priority value of 0 to the lowest priority value, which is - // returned by "minimum_priority_queue ()". Returns 0 on success, - // or -1 if an invalid handle was supplied. // = Access the platform-independent priority value of the lowest-priority // thread. @@ -234,13 +241,13 @@ public: status_t status () const; // = Access the current output (debugging) level. + /// Default is 0; set to 1 to print out schedule, by task. Set + /// to higher than one for debugging info. u_int output_level () const; - // Default is 0; set to 1 to print out schedule, by task. Set - // to higher than one for debugging info. // = Set the scheduler output (debugging) level. + /// the only supported levels are 0 (quiet), 1 (verbose) and 2 (debug) void output_level (const u_int level); - // the only supported levels are 0 (quiet), 1 (verbose) and 2 (debug) int add_dependency(RT_Info* rt_info, Dependency_Info& d); @@ -255,10 +262,10 @@ public: u_long min_dispatch_id () const; u_long max_dispatch_id () const; + /// provide the thread priority and queue type for the given priority level virtual int dispatch_configuration (const Preemption_Priority &p_priority, OS_Priority& priority, Dispatching_Type & d_type); - // provide the thread priority and queue type for the given priority level protected: @@ -268,18 +275,18 @@ protected: ACE_DynScheduler (); + /// thread scheduling method: sets up array of pointers to task + /// entries that are threads, calls internal thread scheduling method status_t schedule_threads ( ACE_Unbounded_Set<RtecScheduler::Scheduling_Anomaly *> &anomaly_set); - // thread scheduling method: sets up array of pointers to task - // entries that are threads, calls internal thread scheduling method + /// dispatch scheduling method: sets up an array of dispatch entries, + /// calls internal dispatch scheduling method. status_t schedule_dispatches ( ACE_Unbounded_Set<RtecScheduler::Scheduling_Anomaly *> &anomaly_set); - // dispatch scheduling method: sets up an array of dispatch entries, - // calls internal dispatch scheduling method. + /// = store assigned information back into the RT_Infos virtual status_t store_assigned_info (void); - // = store assigned information back into the RT_Infos // = Set the minimum priority value. void minimum_priority_queue (const Preemption_Priority minimum_priority_queue_number); @@ -297,82 +304,84 @@ protected: // protected pure virtual member functions // ///////////////////////////////////////////// + /// = determine the minimum critical priority number virtual Preemption_Priority minimum_critical_priority () = 0; - // = determine the minimum critical priority number + /// internal sorting method: this orders the dispatches by + /// static priority and dynamic and static subpriority. virtual status_t sort_dispatches (Dispatch_Entry **, u_int) = 0; - // internal sorting method: this orders the dispatches by - // static priority and dynamic and static subpriority. + /// = assign priorities to the sorted dispatches virtual status_t assign_priorities ( Dispatch_Entry **dispatches, u_int count, ACE_Unbounded_Set<RtecScheduler::Scheduling_Anomaly *> &anomaly_set) = 0; - // = assign priorities to the sorted dispatches + /// = assign dynamic and static sub-priorities to the sorted dispatches virtual status_t assign_subpriorities ( Dispatch_Entry **dispatches, u_int count, ACE_Unbounded_Set<RtecScheduler::Scheduling_Anomaly *> &anomaly_set) = 0; - // = assign dynamic and static sub-priorities to the sorted dispatches + /// = schedule a dispatch entry into the timeline being created virtual status_t schedule_timeline_entry (Dispatch_Entry &dispatch_entry, ACE_Unbounded_Queue <Dispatch_Entry *> &reschedule_queue) = 0; - // = schedule a dispatch entry into the timeline being created //////////////////////////// // protected data members // //////////////////////////// + /// The minimum OS thread priority value that the application specified (in + /// its call to init ()). OS_Priority minimum_priority_; - // The minimum OS thread priority value that the application specified (in - // its call to init ()). + /// The maximum OS thread priority value that the application specified (in + /// its call to init ()). OS_Priority maximum_priority_; - // The maximum OS thread priority value that the application specified (in - // its call to init ()). + /// Collection of known tasks. Task_Entry *task_entries_; - // Collection of known tasks. + /** + * An array of pointers to task entries which wrap RT_Infos. It is + * sorted by the DFS finishing time and then the resulting topological + * over the call graph is used both to check for call chain cycles and + * to correctly propagate scheduling information away from the threads. + */ Task_Entry **ordered_task_entries_; - // An array of pointers to task entries which wrap RT_Infos. It is - // sorted by the DFS finishing time and then the resulting topological - // over the call graph is used both to check for call chain cycles and - // to correctly propagate scheduling information away from the threads. + /// identifies dispatch entries whose underlying + /// Task Entries delineate threads ACE_Unbounded_Set <Dispatch_Entry *> *thread_delineators_; - // identifies dispatch entries whose underlying - // Task Entries delineate threads + /// An array of pointers to task entries which initiate call chains. + /// It is sorted by the schedule_threads method defined in the derived class. Dispatch_Entry **ordered_thread_dispatch_entries_; - // An array of pointers to task entries which initiate call chains. - // It is sorted by the schedule_threads method defined in the derived class. + /// the set of dispatch entries ACE_Unbounded_Set <Dispatch_Entry *> *dispatch_entries_; - // the set of dispatch entries + /// Collection of dispatch configuration entries. ACE_Unbounded_Set <Config_Info *> *config_info_entries_; - // Collection of dispatch configuration entries. + /// expanded set of dispatch entries (all dispatch entries produced by + /// expanding sub-frames to the total frame size during timeline creation) ACE_Unbounded_Set <Dispatch_Entry *> *expanded_dispatches_; - // expanded set of dispatch entries (all dispatch entries produced by - // expanding sub-frames to the total frame size during timeline creation) + /// An array of pointers to dispatch entries. It is + /// sorted by the schedule_dispatches method. Dispatch_Entry **ordered_dispatch_entries_; - // An array of pointers to dispatch entries. It is - // sorted by the schedule_dispatches method. + /// the number of dispatch entries in the schedule u_int dispatch_entry_count_; - // the number of dispatch entries in the schedule + /// the number of dispatch entries in the schedule u_int threads_; - // the number of dispatch entries in the schedule + /// Ordered MultiSet of timeline entries. ACE_Ordered_MultiSet <TimeLine_Entry_Link> *timeline_; - // Ordered MultiSet of timeline entries. private: @@ -399,24 +408,24 @@ private: // private member functions // ////////////////////////////// + /// Create a timeline. status_t create_timeline (); - // Create a timeline. + /// this prints a dispatch timeline to the specified file status_t output_dispatch_timeline (const char *filename); status_t output_dispatch_timeline (FILE *file); - // this prints a dispatch timeline to the specified file + /// this prints a preemption timeline to the specified file status_t output_preemption_timeline (const char *filename); status_t output_preemption_timeline (FILE *file); - // this prints a preemption timeline to the specified file + /// this prints a scheduling viewer timeline to the specified file status_t output_viewer_timeline (const char *filename); status_t output_viewer_timeline (FILE *file); - // this prints a scheduling viewer timeline to the specified file + /// this prints the scheduling parameters and assigned priorities to the specified file status_t output_dispatch_priorities (const char *filename); status_t output_dispatch_priorities (FILE *file); - // this prints the scheduling parameters and assigned priorities to the specified file // = Set up the task entry data structures status_t setup_task_entries (void); @@ -452,16 +461,16 @@ private: // update the scheduling parameters for the previous priority level void update_priority_level_params (); + /// propagate the dispatch information from the + /// threads throughout the call graph status_t propagate_dispatches ( ACE_Unbounded_Set<RtecScheduler::Scheduling_Anomaly *> &anomaly_set, ACE_CString & unresolved_locals, ACE_CString & unresolved_remotes); - // propagate the dispatch information from the - // threads throughout the call graph + /// calculate utilization, frame size, etc. status_t calculate_utilization_params (); - // calculate utilization, frame size, etc. // the following functions are not implememented ACE_DynScheduler (const ACE_DynScheduler &); @@ -471,27 +480,27 @@ private: // private data members // ////////////////////////// + /// This protects access to the scheduler during configuration runs. LOCK lock_; - // This protects access to the scheduler during configuration runs. + /// Collection of known tasks. ACE_Unbounded_Set <RT_Info *> rt_info_entries_; - // Collection of known tasks. + /// The number of task handles dispensed so far. u_int handles_; - // The number of task handles dispensed so far. + /// Destination file of Scheduler output from the configuration run. const char *runtime_filename_; - // Destination file of Scheduler output from the configuration run. + /// Destination file of all rt_info data from the configuration run. const char *rt_info_filename_; - // Destination file of all rt_info data from the configuration run. + /// The destination of the timeline. const char *timeline_filename_; - // The destination of the timeline. + /// A binding of name to rt_info. This is the mapping for every + /// rt_info in the process. Info_Collection info_collection_; - // A binding of name to rt_info. This is the mapping for every - // rt_info in the process. u_int tasks_; @@ -499,32 +508,36 @@ private: u_int output_level_; + /// minimum frame size for all tasks u_long frame_size_; /* 100 nanosec */ - // minimum frame size for all tasks + /// minimum frame size for guaranteed schedulable tasks u_long critical_set_frame_size_; /* 100 nanosec */ - // minimum frame size for guaranteed schedulable tasks + /// total utilization for all tasks double utilization_; - // total utilization for all tasks + /// minimum frame size for guaranteed schedulable tasks double critical_set_utilization_; - // minimum frame size for guaranteed schedulable tasks + /** + * The platform-independent priority value of the Event Channel's + * minimum priority dispatch queue. The value of the maximum priority + * dispatch queue is always 0. + */ Preemption_Priority minimum_priority_queue_; - // The platform-independent priority value of the Event Channel's - // minimum priority dispatch queue. The value of the maximum priority - // dispatch queue is always 0. + /** + * The platform-independent priority value of the minimum priority dispatch + * queue whose operations are guaranteed to be schedulable. The value of + * the maximum priority dispatch queue is always 0, -1 indicates none can + * be guaranteed. + */ Preemption_Priority minimum_guaranteed_priority_queue_; - // The platform-independent priority value of the minimum priority dispatch - // queue whose operations are guaranteed to be schedulable. The value of - // the maximum priority dispatch queue is always 0, -1 indicates none can - // be guaranteed. + /// indicates whether the a valid schedule has been generated since the last + /// relevant change (addition, alteration or removal of an RT_Info, etc.) u_int up_to_date_; - // indicates whether the a valid schedule has been generated since the last - // relevant change (addition, alteration or removal of an RT_Info, etc.) u_long min_dispatch_id_; |