- Gettext support to resource policies descriptions.

- Renamed default_resource_policy_manager to match the design.
- Audited some other files.


git-svn-id: svn://svn.gna.org/svn/sgpemv2/trunk@1232 3ecf2c5c-341e-0410-92b4-d18e462d057c

plugins/pyloader/src/python_cpu_policy.hh

@@ -36,14 +36,20 @@
 
 namespace sgpem
 {
-  /** \brief A specialization of abstract class Policy
-
-   Implements the Policy abstract class specified in the backend component to allow 
-   user-written Python policies to run.
-
-   This class represents a policy written in Python. Its methods interact with Python interpreter.
-   See the documentation of class Policy for more detailed informations.
-  */
+  /// \brief A specialization of abstract class Policy
+  ///
+  /// Implements the Policy abstract class specified in the backend component to allow 
+  /// user-written Python policies to run.
+  ///
+  /// This class represents a policy written in Python. Its methods interact 
+  /// with Python interpreter.
+  /// See the documentation of class Policy for more detailed informations.
+  ///
+  /// Since both the methods get_name() and get_description() must be available before
+  /// backend::Policy activation, then map them to the class name and the return of 
+  /// the __doc__() method, respectively.
+  /// That information can be obtained statically (without
+  /// instantiating an object of that class).
   class PythonCPUPolicy;
 
   class PythonCPUPolicyManager;
@@ -55,58 +61,123 @@ namespace sgpem
     /// \brief Constructor taking the name of the policy.
     ///
     /// Constructor taking the name of the policy.
+    /// Perform the first half of the two-staged construction
     ///
-    /// \param name the name of the policy
+    /// A ::PythonPolicy object is instantiated as soon as its ::PythonPolicyManager 
+    /// calls collect_policies(). In order to save memory, since only a small subset 
+    /// of policies can be activated in a given time frame, this constructor only 
+    /// takes care to determine the policy name and description, without actually 
+    /// preparing a separate PyInterpreter and/or PyThreadState.
+    /// @see activate().
+    /// @throw an exception when the policy is malformed and therefore not usable.
+    /// @param name the name of the policy
     PythonCPUPolicy(const char* name) throw(MalformedPolicyException);
 
     /// \brief Standard virtual destructor
     ///
     virtual ~PythonCPUPolicy();
 
-    /**
-     Calls the method \c async_configure
-    */
-    void   configure() throw(UserInterruptException, MalformedPolicyException);
+    /// \brief Configures the policy, asynchronously.
+    ///
+    /// Configures the policy, asynchronously. Calls the method \c async_configure
+    /// Performs the following operations in this order:
 
-    /**
-     Calls the method \c async_sort_queue
-    */
-    void    sort_queue() const throw(UserInterruptException, MalformedPolicyException);
+    /// -# Erases the content of the PolicyParameters attribute
+    /// -# Calls associated method async_configure() from the loaded 
+    /// ::ScriptAdapter, which has been properly initialized from the activate() method
+    /// -# Wait for the async call to return, calling wait_unlock()
+    /// @throw an exception when the policy is malformed and therefore not usable,
+    /// or when the policy is taking too long to terminate its work.
+    /// @see ::CPUPolicy::configure().
+    void configure() throw(UserInterruptException, MalformedPolicyException);
 
-    /**
-     \returns A textual description of this policy.
-    */
-    Glib::ustring          get_description() const;
+    /// \brief Sorts the queue, asynchronously.
+    ///
+    /// Sorts the queue, asynchronously. Calls the method \c async_sort_queue.
+    /// @throw an exception when the policy is malformed and therefore not usable,
+    /// or when the policy is taking too long to terminate its work.
+    /// @see ::CPUPolicy::sort_queue().
+    void sort_queue() const throw(UserInterruptException, MalformedPolicyException);
 
-    Glib::ustring          get_name() const;
+    /// \brief Returns a textual description of the policy.
+    ///
+    /// Returns a textual description of this policy.
+    /// Tries to get the result of calling __doc__() of the corresponding 
+    /// Python-implemented Policy object, if available. Else, returns the empty string.
+    /// @return long description of the policy.
+    /// @see ::CPUPolicy::get_description().
+    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, MalformedPolicyException);
+    /// \brief Returns a human-readable name of this policy.
+    ///
+    /// Returns a human-readable name of this policy.
+    /// The name of the script file, stripped by its extension --
+    /// typically, it's regexp(/.py(c?)/i)
+    /// @return the name of this policy.
+    /// @see ::CPUPolicy::get_name().
+    Glib::ustring get_name() const;
 
-    /**
-     \returns The integer value of its time-slice.
-    */
-    int    get_time_slice() const throw(UserInterruptException, MalformedPolicyException);
+    /// \brief Returns whether this policy is preemptive or not, asynchronously.
+    ///
+    /// Returns whether this policy is preemptive or not, asynchronously.
+    /// Calls ScriptAdapter::async_is_preemptive(). Waits for an answer into wait_unlock()
+    /// @throw an exception when the policy is malformed and therefore not usable,
+    /// or when the policy is taking too long to terminate its work.
+    /// @return \c TRUE if the policy is preemptive.
+    /// @return \c FALSE if the policy is not preemptive.
+    /// @see ::CPUPolicy::is_pre_emptive().
+    bool is_pre_emptive() const throw(UserInterruptException, MalformedPolicyException);
 
+    /// \brief Returns the lenght of the time slice, asynchronously.
+    ///
+    /// Returns the lenght of the time slice, asynchronously.
+    /// Calls ScriptAdapter::async_get_timeslice(). Waits for an answer into wait_unlock()
+    /// @throw an exception when the policy is malformed and therefore not usable,
+    /// or when the policy is taking too long to terminate its work.
+    /// @return the lenght of the time slice.
+    /// @see ::CPUPolicy::get_time_slice().
+    int get_time_slice() const throw(UserInterruptException, MalformedPolicyException);
+
+    /// \brief Load the corresponding Python module and initialize a new Policy object (in Python).
+    ///
+    /// It will have its own PyThreadState and/or PyInterpreter.
+    /// @throw an exception when the policy is malformed and therefore not usable,
+    /// or when the policy is taking too long to terminate its work.
+    /// @see ::CPUPolicy::activate().
     void activate() throw(UserInterruptException, MalformedPolicyException);
 
+    /// \brief Activates the policy.
+    ///
+    /// Cleanup operations to perform before another policy is loaded.
+    /// @see ::CPUPolicy::deactivate().
     void deactivate();
 
   private:
     PythonCPUPolicy(const PythonCPUPolicy&);
     PythonCPUPolicy& operator=(const PythonCPUPolicy&);
 
+    /// \brief Helps in implementing an asynchronous call to a method.
+    ///
+    /// Enters in a loop waiting for a ::ScriptAdapter method to return. If this 
+    /// doesn't happen before a timeout expires, puts Policy and the Python 
+    /// interpreter in a safe state and throws UserInterruptException.
+    ///
+    /// After an "async*()" call, the global Python interpreter lock has to be 
+    /// released. This is necessary to let the Python threads to run. 
+    /// After having waited for a specified amount of time (we're polling), 
+    /// the lock is taken again, and we check if the thread has finished via 
+    /// the mutex present in ::ScriptAdapter. If so, wait_unlock() terminates 
+    /// successfully. Else it stays in its main loop.
     void wait_unlock() const throw(UserInterruptException, MalformedPolicyException);
+
+    /// \brief Returns a brief description of a thrown exception. 
+    /// Returns the description of the exception occurred.
     static std::string get_exception_information();
 
     static Glib::StaticRecMutex _mtx;
     
     PyObject* _upolicy_dict;
     PyObject* _adapter;
-
     Glib::ustring _name;
     Glib::ustring _description;
   };

plugins/pyloader/src/python_cpu_policy_manager.hh

@@ -31,28 +31,58 @@
 
 namespace sgpem
 {
-  //class CPUPolicyManager;
+ 
+  /// \brief Manages Python user-implemented policies
+  ///
+  /// Manages the creation, the organization and the destruction of the 
+  /// cpu policies implemented using Python.
+  /// 
+  /// It is also responsible for handling malformed policies: as soon as the
+  /// application detects the presence of a malformed policy, it will ask this
+  /// class to terminate the Python interpreter and to reinitialize the objects
+  /// which were previously created by the manager itself.
   class PythonCPUPolicyManager;
 
-  /** \brief Manages Python user-implemented policies
-   * 
-   * This singleton manages the creation and destruction 
-   * of a Python policy.
-   */
   class SG_DLLEXPORT PythonCPUPolicyManager : public CPUPolicyManager
   {
   public:
+
+    /// \brief Standard constructor.
+    ///
+    /// Standard constructor.
+    /// Calls collect_policies() to instantiate all manageable .py policy scripts.
     PythonCPUPolicyManager();
+
+    /// \brief Standard virtual destructor.
+    ///
+    /// Standard virtual desctuctor.
     ~PythonCPUPolicyManager();
 
+    /// \brief Returns policies found and instantiated by collect_policies().
+    ///
+    /// Returns policies found and instantiated by collect_policies().
+    /// \return the policies found and instantiated by collect_policies().
     const std::vector<CPUPolicy*>&  get_avail_policies();
 
   protected:
-    /** The selected and active PyhonCPUPolicy object. */
+
+    /// \brief Scans through directories for loadable Python scripts.
+    /// 
+    /// Scans through directories for loadable Python scripts.
+    /// For each found valid python script, tries to load it, and assess if it contains at least a class which:
+    ///  -# type(classname) is of type "classobj"
+    ///  -# classname.__bases is a tuple containing Policy::Policy
     void collect_policies();
 
   private:
+    /// \brief Standard copy constructor.
+    ///
+    /// Standard private copy constructor.
     PythonCPUPolicyManager(const PythonCPUPolicyManager&);
+
+    /// \brief Standard private operator assign.
+    ///
+    /// Standard private operator assign.
     PythonCPUPolicyManager& operator=(const PythonCPUPolicyManager&);
   };