From 4833658cc1c2b5d1abafeb364564f312440ef4ab Mon Sep 17 00:00:00 2001 From: fpaparel Date: Fri, 24 Feb 2006 15:10:36 +0000 Subject: [PATCH] - added doxygen documentation git-svn-id: svn://svn.gna.org/svn/sgpemv2/trunk@446 3ecf2c5c-341e-0410-92b4-d18e462d057c --- src/backend/observed_subject.hh | 35 ++++- src/backend/policy_parameters.hh | 202 +++++++++++++++++++++----- src/backend/pyloader/python_policy.hh | 40 ++++- src/backend/string_utils.hh | 30 +++- 4 files changed, 257 insertions(+), 50 deletions(-) diff --git a/src/backend/observed_subject.hh b/src/backend/observed_subject.hh index 7d0706b..8025ddf 100644 --- a/src/backend/observed_subject.hh +++ b/src/backend/observed_subject.hh @@ -30,23 +30,42 @@ namespace sgpem { - /** - Abstract class which represents an observed entity who calls Update() in all Observer objects. - See "Observer Pattern" for more information. - */ + class ObservedSubject; - + + /** \brief Represents an observed entity. + + Abstract class which represents an observed entity. It calls Update() in all Observer objects + which are attached to it. See the "Observer Pattern" for more informations. + */ class SG_DLLEXPORT ObservedSubject { public: virtual ~ObservedSubject() =0; - + + /** + This method calls Update() on each attached Observer. It should be called when the internal state + of the ObservedSubject is changed and Observers have to be updated. + */ void notify(); + + + /** + \brief Adds an Observer object to the internal list. + */ void attach(sgpem::Observer*); + + + /** + \brief Removes an Observer object from the internal list. + + \returns TRUE if the Observer object has been previously attached (is found in the list); + \returns FALSE otherwise. + */ bool detach(sgpem::Observer*); - + private: - std::vector _attached; + std::vector _attached; }; } //~ namespace sgpem diff --git a/src/backend/policy_parameters.hh b/src/backend/policy_parameters.hh index a9847bb..482b413 100644 --- a/src/backend/policy_parameters.hh +++ b/src/backend/policy_parameters.hh @@ -30,87 +30,223 @@ namespace sgpem { - class PolicyParametersException : public std::runtime_error + class PolicyParametersException : public std::runtime_error { public: PolicyParametersException(char* msg): std::runtime_error(msg) {} }; class PolicyParameters; - - - /** \brief - Represents all configurable parameters of a single scheduling algorithm. Is is used by the user - interface: it's useful to know which parameters the user will be asked for. - Each Policy object owns only one instance of this class. - */ - class SG_DLLEXPORT PolicyParameters + + + /** \brief Represents all configurable parameters of a single scheduling policy. + + Represents all configurable parameters of a single scheduling policy. Is is used by the user + interface: it serves to know which parameters the user will be asked for. + Each Policy object owns only one instance of this class. + */ + class SG_DLLEXPORT PolicyParameters { public: template class Parameter; - - - //methods to CREATE PARAMETERS + + //####################################### + //########## methods to CREATE PARAMETERS + //####################################### + + /**\brief Registers an INTEGER parameter. + + This method adds an INTEGER parameter to the list of parameters represented by this class. + + \warning If a parameter named \e name already exists it will be replaced by this one. + \param name The name of the parameter. This string will be used to refer to this parameter + in the methods set_int(...), get_int(...) and get_registered_int_parameters(...). + \param lower_bound The lower limitation of the value which can be set with set_int(...). + \param upper_bound The upper limitation of the value which can be set with set_int(...). + \param required Denotes if this parameter is required by the policy. + \param default_value The initial value of this parameter. (If not specified it's set to 0). + */ void register_int(Glib::ustring name,const int& lower_bound, const int& upper_bound, const bool& required, const int& default_value = 0); + + /**\brief Registers a FLOAT parameter. + + This method adds a FLOAT parameter to the list of parameters represented by this class. + + \warning If a parameter named \e name already exists it will be replaced by this one. + \param name The name of the parameter. This string will be used to refer to this parameter + in the methods set_float(...), get_float(...) and get_registered_float_parameters(...). + \param lower_bound The lower limitation of the value which can be set with set_int(...). + \param upper_bound The upper limitation of the value which can be set with set_int(...). + \param required Denotes if this parameter is required by the policy. + \param default_value The initial value of this parameter. (If not specified it's set to 0.0f). + */ void register_float(Glib::ustring name,const float& lower_bound, const float& upper_bound, const bool& required, const float& default_value = 0.0f); + + /**\brief Registers a STRING parameter. + + This method adds a STRING parameter to the list of parameters represented by this class. + Note that there are no limitations to the value thath this parameter can assume. + + \warning If a parameter named \e name already exists it will be replaced by this one. + \param name The name of the parameter. This string will be used to refer to this parameter + in the methods set_string(...), get_string(...) and get_registered_string_parameters(...). + \param required Denotes if this parameter is required by the policy. + \param default_value The initial value of this parameter. (If not specified it's set to the empty string). + */ void register_string(Glib::ustring name, const bool& required, const Glib::ustring& default_value = ""); - + + + /**\brief Deletes all registered parameters. + */ void clear(); - - //methods to RETRIEVE CREATED PARAMETERS + + + //############################################# + //###### methods to RETRIEVE CREATED PARAMETERS + //############################################# + + /** \brief Permits to retrieve all registered INTEGER parameters + \returns a map of INTEGER parameters identfied by their name + */ std::map > get_registered_int_parameters() const; + + /** \brief Permits to retrieve all registered FLOAT parameters + \returns a map of FLOAT parameters identfied by their name + */ std::map > get_registered_float_parameters() const; + + /** \brief Permits to retrieve all registered STRING parameters + \returns a map of STRING parameters identfied by their name + */ std::map > get_registered_string_parameters() const; - - //methods to SET the VALUE of PARAMETERS - + + + //############################################# + //###### methods to SET the VALUE of PARAMETERS + //############################################# + + /** \brief Sets the value of a registred INTEGER parameter + + Permits to change the value of a parameter identified by "name" + + \returns TRUE if the specified "name" maps to a registered parameter and if "value" doesn't + exceed the bounds proper to that parameter + \returns FALSE if the parameter named "name" is not found or if "value" exceeds the bounds + */ bool set_int(Glib::ustring name, const int& value); + + /** \brief Sets the value of a registred FLOAT parameter + + Permits to change the value of a parameter identified by "name" + + \returns TRUE if the specified "name" maps to a registered parameter and if "value" doesn't + exceed the bounds proper to that parameter + \returns FALSE if the parameter named "name" is not found or if "value" exceeds the bounds + */ bool set_float(Glib::ustring name, const float& value); + + /** \brief Sets the value of a registred STRING parameter + + Permits to change the value of a parameter identified by "name" + + \returns TRUE if the specified "name" maps to a registered parameter and if "value" doesn't + exceed the bounds proper to that parameter + \returns FALSE if the parameter named "name" is not found or if "value" exceeds the bounds + */ bool set_string(Glib::ustring name, const Glib::ustring& value); - - //methods to GET the VALUE of PARAMETERS - + + + //############################################# + //###### methods to GET the VALUE of PARAMETERS + //############################################# + + /** \brief Returns the value of an INTEGER parameter + \returns the INTEGER value of the parameter named \e name + \throws PolicyParametersException if the parameter named \e name has not been registered + */ int get_int(Glib::ustring name) const; + + /** \brief Returns the value of an FLOAT parameter + \returns the FLOAT value of the parameter named \e name + \throws PolicyParametersException if the parameter named \e name has not been registered + */ float get_float(Glib::ustring name) const; + + /** \brief Returns the value of an STRING parameter + \returns the STRING value of the parameter named \e name + \throws PolicyParametersException if the parameter named \e name has not been registered + */ Glib::ustring get_string(Glib::ustring name) const; - - + + private: std::map > int_map; std::map > float_map; std::map > string_map; }; - - - /** - This class is useful only to store informations about each parameter. No checks + + + /** \brief This class represents a sigle parameter of type \c T + + This class is useful only to store informations about each parameter. No checks on the values entered are done. - */ + */ template class PolicyParameters::Parameter { public: + + /** \brief Constructs the parameter + \param name The name of the parameter. This string will be used to refer to this parameter, thus it MUST + be uniqe (one string identifies \b only ONE parameter) + \param value The initial value of this parameter + \param lower_bound The lower limitation of the value which can be set with set_int(...). + \param upper_bound The upper limitation of the value which can be set with set_int(...). + \param required Denotes if this parameter is required by the policy. + \param default_value The initial value of this parameter. (If not specified it's set to 0). + */ Parameter(Glib::ustring name, const T& value, const T& lower_bound, const T& upper_bound, const bool& required, const T& default_value = 0); + + /** \returns The name of the parameter (its UNIQUE key) + */ Glib::ustring get_name() const; + + /** \returns The lower bound + */ T get_lower_bound() const; + + /** \returns The upper bound + */ T get_upper_bound() const; + + /** \returns TRUE if this parameter is required + */ bool is_required() const; + + /** \returns Its default value + */ T get_default() const; + + /** \returns Its actual value + */ T get_value() const; - + + /** \brief Changes the value of the parameter. + \warning NO CHECK is done whether the value repects its bounds!! + */ void set_value(const T&); - + private: Glib::ustring _name; T _value; T _lower_bound; - T _upper_bound; + T _upper_bound; bool _is_required; T _default; }; - - + + }//~ namespace sgpem #include "../templates/parameter.tcc" diff --git a/src/backend/pyloader/python_policy.hh b/src/backend/pyloader/python_policy.hh index 907bc22..38d6310 100644 --- a/src/backend/pyloader/python_policy.hh +++ b/src/backend/pyloader/python_policy.hh @@ -36,24 +36,52 @@ namespace sgpem class PythonPolicy; class PythonPolicyManager; class UserInterruptException; - + + /** \brief A specialization of abstract class Policy + + This class represents a policy written in Python. Its methods interact with Python interpreter. + See the documentation of class Policy for more detailed informations. + */ class SG_DLLEXPORT PythonPolicy : public Policy { - public: + public: //only PythonPolicyManager can create a PythonPolicy object friend class PythonPolicyManager; - + virtual ~PythonPolicy(); - + + /** + Calls the method \c async_configure + */ void configure() throw(UserInterruptException); + + /** + Calls the method \c async_sort_queue + */ void sort_queue(Scheduler::event) const throw(UserInterruptException); + + /** + \returns A textual description of this policy. + */ Glib::ustring get_description() const; + + /** + \returns \c TRUE if the policy is preemptive. + \returns \c FALSE if the policy is not preemptive. + */ bool is_pre_emptive() const throw(UserInterruptException); - int get_time_slice() const throw(UserInterruptException); + + /** + \returns The integer value of its time-slice. + */ + int get_time_slice() const throw(UserInterruptException); // Singing with Caipha's voice: "must die, must die, this method must die!" + /** + Changes the time-slice of the policy. + */ void set_time_slice(const int&); - + private: PythonPolicy(const char* name); PythonPolicy(const PythonPolicy&); diff --git a/src/backend/string_utils.hh b/src/backend/string_utils.hh index b0f44a8..e1bb3ff 100644 --- a/src/backend/string_utils.hh +++ b/src/backend/string_utils.hh @@ -26,13 +26,37 @@ #include #include "glibmm/ustring.h" + /**\brief This function tries to convert a string into an integer value. + The string can contain only digits and the minus character (for negative numbers). + + \returns TRUE if ths string represent a valid integer number + \returns FALSE otherwise + */ bool SG_DLLEXPORT string_to_int(const Glib::ustring&, int&); - + + + /**\brief This function converts an integer value into a string. + + There is no return value because this function always succeeds. + */ void SG_DLLEXPORT int_to_string(const int&, Glib::ustring&); - + + + /**\brief This function converts a float value into a string. + + There is no return value because this function always succeeds. + */ void SG_DLLEXPORT float_to_string(const float&, Glib::ustring&); - + + + /**\brief This function tries to convert a string into a float value. + + The string can contain only digits, the minus, plus and dot (-+.) characters. If not, + the value 0 is assigned. + + There is no return value because this function always succeeds, even if the string is badly formed. + */ void SG_DLLEXPORT string_to_float(const Glib::ustring&, float&);