- added doxygen documentation

git-svn-id: svn://svn.gna.org/svn/sgpemv2/trunk@446 3ecf2c5c-341e-0410-92b4-d18e462d057c
This commit is contained in:
fpaparel 2006-02-24 15:10:36 +00:00
parent ed389f8b37
commit 4833658cc1
4 changed files with 257 additions and 50 deletions

View File

@ -30,19 +30,38 @@
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:

View File

@ -38,9 +38,10 @@ namespace sgpem
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.
/** \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
@ -49,29 +50,132 @@ namespace sgpem
template<typename T>
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<Glib::ustring, Parameter<int> > 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<Glib::ustring, Parameter<float> > 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<Glib::ustring, Parameter<Glib::ustring> > 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;
@ -83,7 +187,8 @@ namespace sgpem
};
/**
/** \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.
*/
@ -91,14 +196,45 @@ namespace sgpem
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:

View File

@ -37,6 +37,11 @@ namespace sgpem
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:
@ -45,13 +50,36 @@ namespace sgpem
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:

View File

@ -26,13 +26,37 @@
#include <iostream>
#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&);