diff --git a/src/backend/dynamic_schedulable.hh b/src/backend/dynamic_schedulable.hh index 714d865..419a657 100644 --- a/src/backend/dynamic_schedulable.hh +++ b/src/backend/dynamic_schedulable.hh @@ -27,17 +27,21 @@ namespace sgpem { + + /// \brief Desribes the state of a schedulable entity in a particular moment + /// of the simulation + /// + /// Contains part of the information used by the scheduling policies to + /// perform scheduling. + /// Objects of subclasses of ::DynamicSchedulable may be created by the system + /// via the Scheduler.step_forward() method (which then inserts them into a + /// ::ConcreteEnvironment), or by the user on a resetted ::History by creating + /// one of them anew. + /// + /// These objects may be destroyed only by resetting an ::History, or via one + /// of its methods. class DynamicSchedulable; - /** \brief Desribes the state of a schedulable entity in a particular moment - * of the simulation - * - * This class stores part of the information deeded by the Scheduler to - * manage processes and other ones. - * - * Objects of type DynamicSchedulable are created by the Scheduler and are - * destroyed by SimulationStatus if they are linked to it or by the Scheduler. - */ class SG_DLLLOCAL DynamicSchedulable : public virtual Schedulable { public: @@ -54,28 +58,117 @@ namespace sgpem */ virtual bool operator==(const Schedulable&) const; + /// \brief Returns the name of the Schedulable. + /// + /// Returns the name of the Schedulable. + /// It is fetched from the associated ::StaticSchedulable object. + /// \return the name of the Schedulable. virtual Glib::ustring get_name() const; + /// \brief Returns the arrival time of the Schedulable. + /// + /// Returns the arrival time of the Schedulable. + /// The arrival time is the instant of the simulation when + /// the state of the Schedulable is switched from future to + /// ready. + /// + /// The arrival time is a static (respect to the simulation) property. + /// It is fetched from the associated ::StaticSchedulable object. + /// \return the arrival time of the Schedulable. virtual unsigned int get_arrival_time() const; + /// \brief Returns the base priority of the Schedulable. + /// + /// Returns the base priority of the Schedulable. + /// The base priority of a Schedulable is an indicator of the importance of + /// the Schedulable. Priority-sensitive policies usually give better services + /// to more important Schedulables. + /// + /// Base priority is summed to the priority push to obtain the current priority + /// of the schedulable, which is the real parameter policies read. + /// + /// The base priority is a static (respect to the simulation) property. + /// It is fetched from the associated ::StaticSchedulable object. + /// \return the base priority of the Schedulable. virtual int get_base_priority() const; + /// \brief Returns the total required CPU time of the Schedulable. + /// + /// Returns the total required CPU time of the Schedulable. + /// The total required CPU time is the time the Schedulable needs to + /// complete its work. + /// + /// When a Schedulable's elapsed CPU time equals the total required CPU time + /// its state is set to "terminated". + /// + /// The total required CPU time is a static (respect to the simulation) property. + /// It is fetched from the associated ::StaticSchedulable object. + /// \return the total required CPU time of the Schedulable. virtual unsigned int get_total_cpu_time() const; + /// \brief Returns the current priority push of the Schedulable. + /// + /// Returns the current priority push of the Schedulable. + /// The current priority push of a Schedulable is an indicator of the local + /// importance of the Schedulable. Priority-sensitive policies usually give + /// better services to more important Schedulables. + /// + /// Base priority is summed to the priority push to obtain the current priority + /// of the schedulable, which is the real parameter policies read. + /// + /// The priority push is a dynamic (respect to the simulation) property. + /// \return the current priority push of the Schedulable. virtual int get_priority_push() const; + /// \brief Sets the priority push of the Schedulable, returning the old one. + /// + /// Sets the current priority push of the Schedulable. + /// The current priority push of a Schedulable is an indicator of the local + /// importance of the Schedulable. Priority-sensitive policies usually give + /// better services to more important Schedulables. + /// + /// Base priority is summed to the priority push to obtain the current priority + /// of the schedulable, which is the real parameter policies read. + /// + /// The priority push is a dynamic (respect to the simulation) property. + /// \param new_value the new push to be set. + /// \return the old priority push of the Schedulable. virtual int set_priority_push(int new_value = 0); + /// \brief Returns the current priority of the Schedulable. + /// + /// Returns the current priority of the Schedulable. + /// The current priority of a Schedulable is an indicator of the importance of + /// the Schedulable. Priority-sensitive policies usually give better services + /// to more important Schedulables. + /// + /// Base priority is summed to the priority push to obtain the current priority + /// of the schedulable, which is the real parameter policies read. + /// + /// The current priority is a dynamic (respect to the simulation) property. + /// \return the dynamic priority of the Schedulable. virtual int get_current_priority() const; + /// \brief Returns the elapsed time of the Schedulable. + /// + /// Returns the elapsed time of the Schedulable. + /// The elapsed time is the amount of time a Schedulable has been running + /// until the current instant. + /// + /// The elapsed time is a dynamic (respect to the simulation) property. + /// \return the elapsed time of the Schedulable. virtual unsigned int get_elapsed_time() const = 0; - /** \brief Returns a pointer to the schedulable object - * - * This function returns a reference to the actual schedable object - * represented, along with its status, by this instance. - */ + /// \brief Returns a pointer to the static schedulable object + /// + /// This function returns a reference to the actual schedable object + /// represented, along with its status, by this instance. virtual StaticSchedulable& get_core() = 0; + + /// \brief Returns a constant pointer to the static schedulable object + /// + /// This function returns a constant reference to the actual schedable object + /// represented, along with its status, by this instance. virtual const StaticSchedulable& get_core() const = 0; private: diff --git a/src/backend/sgpemv2/module.hh b/src/backend/sgpemv2/module.hh index 926d6a3..d1b870e 100644 --- a/src/backend/sgpemv2/module.hh +++ b/src/backend/sgpemv2/module.hh @@ -1,4 +1,4 @@ -// src/backend/module.hh - Copyright 2005, 2006, University +// src/backend/sgpemv2/module.hh - Copyright 2005, 2006, University // of Padova, dept. of Pure and Applied // Mathematics // @@ -30,23 +30,65 @@ namespace sgpem { + + /// \brief A link to a loaded DSO object + /// + /// When a plugin is found, PluginManager::rescan_dirs() tries to load it by + /// creating an object of this class. + /// The constructor should throw InvalidPluginException if the plugin isn't + /// a valid SGPEMv2 one. This should be handled directly into + /// PluginManager::rescan_dirs(). class Module; class SG_DLLEXPORT Module : public Glib::Module { public: + + /// \brief Constructor taking an identifier. + /// + /// Constructor taking an identifier. + /// \throw InvalidPluginException If the DSO you're trying to load + /// doesn't export a valid SGPEMv2 backend::Plugin interface. + /// \param identifier A string with the DSO name without any file-extension + /// suffix. This is retrieved by PluginManager::rescan_dirs(). Module(const Glib::ustring& identifier) throw(InvalidPluginException); + /// \brief Enables or disables a plugin + /// + /// Enables/disables a plugin, calling its on_init()/on_exit() exported + /// functions where appropriate. + /// \param enabled whether to enable or disable the module. void set_enabled(bool enabled = true); + /// \brief Returns the name of the module. + /// + /// Calls Plugin::get_name() + /// \return the name of the module. Glib::ustring get_name() const; + /// \brief Returns the author of the module. + /// + /// Calls Plugin::get_author() + /// \return the author of the module. Glib::ustring get_author() const; + /// \brief Returns a description of the module. + /// + /// Calls Plugin::describe() + /// \return a description of the module. Glib::ustring describe() const; + /// \brief Returns the version of the module. + /// + /// Calls Plugin::get_version() + /// \return the version of the module. float get_version() const; + /// \brief Returns whether the module is enabled or disabled. + /// + /// Enables/disables a plugin, calling its on_init()/on_exit() exported + /// functions where appropriate. + /// \param enabled whether to enable or disable the module. bool get_enabled() const; private: @@ -54,7 +96,12 @@ namespace sgpem typedef const char* (*f_ustring)(void); typedef float (*f_float)(void); + /// True if the plugin is enabled, false otherwise + /// bool _enabled; + + /// A string containing the DSO name, stripped of any file-extension suffix + /// Glib::ustring _id; f_void on_init_ptr; diff --git a/src/backend/sgpemv2/plugin.hh b/src/backend/sgpemv2/plugin.hh index 6a85067..8c23011 100644 --- a/src/backend/sgpemv2/plugin.hh +++ b/src/backend/sgpemv2/plugin.hh @@ -1,4 +1,4 @@ -// src/backend/plugin.hh - Copyright 2005, 2006, University +// src/backend/sgpemv2/plugin.hh - Copyright 2005, 2006, University // of Padova, dept. of Pure and Applied // Mathematics // @@ -43,12 +43,12 @@ extern "C" * Sets up the plugin's initial state and * performs needed actions before its usage can start. */ - SG_DLLEXPORT void sgpem__Plugin__on_init(); + SG_DLLEXPORT void sgpem__Plugin__on_init(); - SG_DLLEXPORT void sgpem__Plugin__on_exit(); - SG_DLLEXPORT const char* sgpem__Plugin__describe(); - SG_DLLEXPORT const char* sgpem__Plugin__get_name(); - SG_DLLEXPORT const char* sgpem__Plugin__get_author(); + SG_DLLEXPORT void sgpem__Plugin__on_exit(); + SG_DLLEXPORT const char* sgpem__Plugin__describe(); + SG_DLLEXPORT const char* sgpem__Plugin__get_name(); + SG_DLLEXPORT const char* sgpem__Plugin__get_author(); SG_DLLEXPORT float sgpem__Plugin__get_version(); // To know why SG_DLLEXPORT must go *before* the return diff --git a/src/backend/sgpemv2/schedulable.hh b/src/backend/sgpemv2/schedulable.hh index 84dfbb8..c238cb9 100644 --- a/src/backend/sgpemv2/schedulable.hh +++ b/src/backend/sgpemv2/schedulable.hh @@ -90,7 +90,7 @@ namespace sgpem /// ready. /// /// The arrival time is a static (respect to the simulation) property. - /// \return the arrival time of of the Schedulable. + /// \return the arrival time of the Schedulable. virtual unsigned int get_arrival_time() const = 0; /// \brief Returns the elapsed time of the Schedulable. @@ -100,7 +100,7 @@ namespace sgpem /// until the current instant. /// /// The elapsed time is a dynamic (respect to the simulation) property. - /// \return the elapsed time of of the Schedulable. + /// \return the elapsed time of the Schedulable. virtual unsigned int get_elapsed_time() const = 0; /// \brief Returns the remaining time of the Schedulable. @@ -113,7 +113,7 @@ namespace sgpem /// and the current elapsed CPU time. /// /// The remaining time is a dynamic (respect to the simulation) property. - /// \return the remaining time of of the Schedulable. + /// \return the remaining time of the Schedulable. virtual unsigned int get_remaining_time() const; /// \brief Returns the last aquisition instant of the Schedulable. @@ -126,7 +126,7 @@ namespace sgpem /// Its dual feature is the last release instant. /// /// The last aquisition instant is a dynamic (respect to the simulation) property. - /// \return the last aquisition instant of of the Schedulable. + /// \return the last aquisition instant of the Schedulable. virtual int get_last_acquisition() const = 0; /// \brief Returns the last release instant of the Schedulable. @@ -139,7 +139,7 @@ namespace sgpem /// Its dual feature is the last aquisition instant. /// /// The last release instant is a dynamic (respect to the simulation) property. - /// \return the last release instant of of the Schedulable. + /// \return the last release instant of the Schedulable. virtual int get_last_release() const = 0; /// \brief Returns the base priority of the Schedulable. @@ -153,7 +153,7 @@ namespace sgpem /// of the schedulable, which is the real parameter policies read. /// /// The base priority is a static (respect to the simulation) property. - /// \return the base priority of of the Schedulable. + /// \return the base priority of the Schedulable. virtual int get_base_priority() const = 0; /// \brief Returns the total required CPU time of the Schedulable. @@ -166,7 +166,7 @@ namespace sgpem /// its state is set to "terminated". /// /// The total required CPU time is a static (respect to the simulation) property. - /// \return the total required CPU time of of the Schedulable. + /// \return the total required CPU time of the Schedulable. virtual unsigned int get_total_cpu_time() const = 0; /// \brief Returns the current priority of the Schedulable. @@ -180,7 +180,7 @@ namespace sgpem /// of the schedulable, which is the real parameter policies read. /// /// The current priority is a dynamic (respect to the simulation) property. - /// \return the dynamic priority of of the Schedulable. + /// \return the dynamic priority of the Schedulable. virtual int get_current_priority() const = 0; /// \brief Returns the current priority push of the Schedulable. @@ -194,7 +194,7 @@ namespace sgpem /// of the schedulable, which is the real parameter policies read. /// /// The priority push is a dynamic (respect to the simulation) property. - /// \return the current priority push of of the Schedulable. + /// \return the current priority push of the Schedulable. virtual int get_priority_push() const; /// \brief Sets the priority push of the Schedulable, returning the old one. @@ -209,7 +209,7 @@ namespace sgpem /// /// The priority push is a dynamic (respect to the simulation) property. /// \param new_value the new push to be set. - /// \return the old priority push of of the Schedulable. + /// \return the old priority push of the Schedulable. virtual int set_priority_push(int new_value = 0) = 0; /// \brief Returns the current state of the Schedulable. @@ -220,7 +220,7 @@ namespace sgpem /// states of a schedulable. /// /// The current state is a dynamic (respect to the simulation) property. - /// \return the current state of of the Schedulable. + /// \return the current state of the Schedulable. virtual state get_state() const = 0; /// \brief Serializes this entity using a visitor pattern. diff --git a/src/backend/sgpemv2/simulation_observer.hh b/src/backend/sgpemv2/simulation_observer.hh index 188d42d..c382c2c 100644 --- a/src/backend/sgpemv2/simulation_observer.hh +++ b/src/backend/sgpemv2/simulation_observer.hh @@ -26,12 +26,26 @@ namespace sgpem { class Simulation; + + /// \brief This class instantiates the pattern observer for the target Simulation + /// + /// A SimulationObserver represents an entity which may register to a Simulation + /// to get notifications when the state of the Simulation changes. class SimulationObserver; class SG_DLLEXPORT SimulationObserver { public: + /// \brief Updates the observer with information provided by changed_simulation + /// + /// This method is called whenever the simulation decides that observers should + /// be notified. + /// \param changed_simulation the simulation which notifies an update. virtual void update(const Simulation& changed_simulation) = 0; + + /// \brief Standard virtual destructor. + /// + /// Standard virtual destructor. virtual ~SimulationObserver(); } diff --git a/src/backend/static_resource.hh b/src/backend/static_resource.hh index 4cbbed3..b1dbea3 100644 --- a/src/backend/static_resource.hh +++ b/src/backend/static_resource.hh @@ -26,21 +26,56 @@ namespace sgpem { - class StaticResource; class SerializeVisitor; + /// StaticResource is an object that act for a system resource. + /// It has a name, and a number of places. + /// + /// The attributes stored in a static entity are static in the sense that + /// they are user-set and no inner mechanism of the Backend component may + /// change these attributes without the user having explicitly asked it. + /// + /// This is enforced by not providing any setter method, and by making the + /// copy constructor private. This makes clear that if you want to edit a + /// static entity, you should reset the ::History, remove the old static + /// entity, and create a new dynamic entity for the new static one. class StaticResource { public: + /// \brief Constructor taking a defined name and a number of places. + /// + /// \param name the name of the resource + /// \param places the number of places of the resource StaticResource(const Glib::ustring& name, unsigned int places = 1); + /// \brief Returns the name of the Resource. + /// + /// Returns the name of the Resource. + /// \return the name of the Resource. Glib::ustring get_name() const; + + /// \brief Modifies the name of the Resource. + /// + /// Modifies the name of the Resource. + /// \param name the new name for the Resource. + /// \return the old name of the Resource. Glib::ustring set_name(Glib::ustring name); + /// \brief Returns the number of places of the Resource. + /// + /// Returns the number of places of the Resource. + /// \return the number of places of the Resource. unsigned int get_places() const; + + /// \brief Modifies the number of places of the Resource. + /// + /// Modifies the number of places of the Resource. + /// \param name the new number of places for the Resource. + /// \return the old number of places of the Resource. unsigned int set_places(unsigned int places); private: + /// \brief Private standard copy constructor. StaticResource(const StaticResource&); Glib::ustring _name; diff --git a/src/backend/static_sub_request.hh b/src/backend/static_sub_request.hh index f35ded0..d60a374 100644 --- a/src/backend/static_sub_request.hh +++ b/src/backend/static_sub_request.hh @@ -27,7 +27,21 @@ namespace sgpem { + + + /// \brief Represents the static description of a request. + /// + /// Represents the static description of a request. + /// The attributes stored in a static entity are static in the sense that + /// they are user-set and no inner mechanism of the Backend component may + /// change these attributes without the user having explicitly asked it. + /// + /// This is enforced by not providing any setter method, and by making the + /// copy constructor private. This makes clear that if you want to edit a + /// static entity, you should reset the ::History, remove the old static + /// entity, and create a new dynamic entity for the new static one. class StaticSubRequest; + class StaticRequest; class StaticResource; @@ -36,21 +50,60 @@ namespace sgpem public: typedef SubRequest::resource_key_t resource_key_t; - StaticSubRequest(resource_key_t resource_key, - unsigned int length); + /// \brief Constructor taking the resource id, and the length. + /// + /// Create a StaticSubRequest with assigned StaticResource, + /// for one single places, and for a defined length. + /// \param resource_key the id of the requested resource + /// \param length the time the resource is needed. + StaticSubRequest(resource_key_t resource_key, unsigned int length); + /// \brief Standard virtual destructor. + /// + /// Standard virtual destructor. ~StaticSubRequest(); + /// \brief Returns the id of the requested resource. + /// + /// Returns the id of the requested resource. + /// \return the id of the requested resource. resource_key_t get_resource_key() const; + + /// \brief Changes the requested resource. + /// + /// Changes the requested resource by changing the related id. + /// \param resource_key the id of the new requested resource. + /// \return the id of the old requested resource. resource_key_t set_resource_key(resource_key_t resource_key); + + /// \brief Returns the length of the request. + /// + /// Returns the length of the request. + /// \return the length of the request. unsigned int get_length() const; + + /// \brief Modifies the length of the request. + /// + /// Modifies the length of the request. + /// \param length the new lenght of the request. + /// \return the old length of the request. unsigned int set_length(unsigned int length); private: + /// \brief Private standard copy constructor + /// StaticSubRequest(const StaticSubRequest&); + + /// \brief Private standard operator assingment. + /// StaticSubRequest& operator=(const StaticSubRequest&); + /// The id of the requested resource + /// resource_key_t _resource_key; + + /// How long (how many time cycles) the resource is needed. + /// unsigned int _length; }; diff --git a/src/backend/static_thread.hh b/src/backend/static_thread.hh index 428bdd3..cf39dfb 100644 --- a/src/backend/static_thread.hh +++ b/src/backend/static_thread.hh @@ -34,28 +34,117 @@ namespace sgpem { class StaticProcess; - class StaticThread; class StaticRequest; + /// \brief A StaticThread object is a StaticSchedulable object which describes a + /// thread and offers thread-specific information. + /// + /// A StaticThread object stores the invariant characterization of a thread. + /// It is used together with the Thread object to fulfill the needs of a + /// PublicSchedulable [PublicThread wannabe] user. + /// The attributes stored in a static entity are static in the sense that + /// they are user-set and no inner mechanism of the Backend component may + /// change these attributes without the user having explicitly asked it. + /// + /// This is enforced by not providing any setter method, and by making the + /// copy constructor private. This makes clear that if you want to edit a + /// static entity, you should reset the ::History, remove the old static + /// entity, and create a new dynamic entity for the new static one. + /// + /// One noteworthy thing is the actual meaning of the arrival time of a thread: + /// it is the difference between + /// + /// the instant of the simulation in which this thread requires the CPU + /// for the first time, i.e. the instant at which its creation in the + /// operating system is simulated, + /// + /// and + /// + /// the instant of the simulation in which the process which owns + /// this thread requires the CPU for the first time, i.e. the instant + /// at which its creation in the operating system is simulated. + class StaticThread; + class StaticThread : public StaticSchedulable { public: + + + /// Creates a StaticThread object with definite + /// name, father (pointer), total cpu time required, + /// arrival time (default is 0 [zero]) and base priority (default is 0 [zero]). + /// + /// \param name the name of the thread + /// \param process the father process + /// \param cpu_time the total required cpu time + /// \param arrival_time the arrival time + /// \param base_priority the base priority StaticThread(const Glib::ustring& name, StaticProcess& process, unsigned int cpu_time, unsigned int arrival_time = 0, int base_priority = 0); + /// \brief Standard virtual destructor. + /// + /// Standard virtual destructor. virtual ~StaticThread(); + /// \brief Returns the total required CPU time of the Thread. + /// + /// Returns the total required CPU time of the Thread. + /// The total required CPU time is the time the Thread needs to + /// complete its work. + /// + /// When a Thread's elapsed CPU time equals the total required CPU time + /// its state is set to "terminated". + /// + /// The total required CPU time is a static (respect to the simulation) property. + /// \return the total required CPU time of the Thread. virtual unsigned int get_total_cpu_time() const; + /// \brief Modifies the total required CPU time of the Thread. + /// + /// Modifies the total required CPU time of the Thread. + /// Returns the old total required CPU time of the Thread. + /// The total required CPU time is the time the Thread needs to + /// complete its work. + /// + /// When a Thread's elapsed CPU time equals the total required CPU time + /// its state is set to "terminated". + /// + /// The total required CPU time is a static (respect to the simulation) property. + /// \param cpu_time the new amount of total CPU time required by the thread. + /// \return the old total required CPU time of the Thread. unsigned int set_total_cpu_time(unsigned int cpu_time); + /// \brief Returns the arrival time of the Thread. + /// + /// Returns the arrival time of the Thread. + /// The arrival time is the instant of the simulation when + /// the state of the Thread is switched from future to + /// ready. + /// @see ::StaticThread. + /// \return the arrival time of the Schedulable. virtual unsigned int get_arrival_time() const; + /// \brief Modifies the arrival time of the Thread. + /// + /// Modifies the arrival time of the Thread. + /// The arrival time is the instant of the simulation when + /// the state of the Thread is switched from future to + /// ready. + /// @see ::StaticThread. + /// \return the arrival time of the Schedulable. virtual unsigned int set_arrival_time(unsigned int arrival_time); + /// \brief Returns the parent process of the Thread + /// + /// This StaticThread object represents the invariant description of a thread. + /// That thread belongs to a particular process. + /// That process has an associated invariant description. + /// This method returns an handle to that description. + /// \return the parent process of the Thread virtual StaticProcess& get_process(); // Caller can use directly the vector instead that @@ -65,9 +154,25 @@ namespace sgpem virtual std::vector& get_requests(); private: + + /// \brief Private standard copy constructor. StaticThread(const StaticThread&); + /// The difference between + /// + /// the instant of the simulation in which this thread requires the CPU + /// for the first time, i.e. the instant at which its creation in the + /// operating system is simulated, + /// + /// and + /// + /// the instant of the simulation in which the process which owns + /// this thread requires the CPU for the first time, i.e. the instant + /// at which its creation in the operating system is simulated. unsigned int _start_time_delta; + + /// The total cpu time required by this thread to terminate. + /// unsigned int _required_cpu_time; StaticProcess* _process; std::vector _static_requests;