- Add documentation for classes:

- (C++) PythonPolicyManager
  - (Python) Policy, ScriptAdapter, fcfs


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

src/backend/pyloader/Policy.py

@@ -3,28 +3,123 @@ from Abstract import *
 ## @brief This is the abstract class a user-defined policy
 # should inherit from
 #
-# This class also exposes the method sort, which can be
+# This class also exposes the method sort(), which can be
 # used to easily sort the queue of ready process with a
-# given compare function
+# user-defined given compare function.
 class Policy:
-    ## @var Avoid instantiation of an abstract class
+    ## @var Avoid instantiation of an abstract class.
+    # @see Abstract.Metaclass
     __metaclass__ = Metaclass
-    
-    configure = AbstractMethod('configure')
-    sort_queue = AbstractMethod('sort_queue')
-    is_preemptive = AbstractMethod('is_preemptive')
-    get_time_slice = AbstractMethod('get_time_slice')
-    
-    ## @brief this function implements a quicksort in place
-    # using the SchedulableQueue methods
+
+    ## @brief Configure policy to initial values
     #
-    # The compare parameter should be a user defined function
-    # name returning either True or False, defined like:
+    # This is called just before a simulation starts, and is responsible
+    # to define the parameters the policy wants to expose to the user.
+    # For example, it may make the return value of is_preemptive configurable,
+    # or register an integer value for a the time slice duration.
+    #
+    # @warning How do the user access get_parameters()?
+    #
+    # Should be implemented with signature:
     # @code
-    # def compare(SchedulableA,SchedulableB):
-    #     return SchedulableA.someProperty() < SchedulableB.someProperty()
+    # def configure(self):
+    #      # function body
     # @endcode
     #
+    # @see sgpem::Policy::get_parameters()
+    configure = AbstractMethod('configure')
+
+    ## @brief Sort ready processes queue
+    #
+    # This method is called by the scheduler at each
+    # step of the simulation to sort the ready
+    # processes queue.
+    #
+    # Should be implemented with signature:
+    # @code
+    # def sort_queue(self, event, queue):
+    #      # function body
+    # @endcode
+    #
+    # @param event Enumeration value of type Scheduler::Event,
+    # needed by some policies to know the reason of
+    # the call
+    # @param queue The sgpem::SchedulableQueue to be sorted.
+    # Only some methods of it are implemented,
+    # notably get_item_at(position),
+    # swap(positionA, positionB) and size().
+    #
+    # @see Policy.sort()
+    sort_queue = AbstractMethod('sort_queue')
+
+    ## @brief Returns whether the policy wants to be preemptive,
+    # other than by normal time slice termination
+    #
+    # See the return value for a complete explanation. Please
+    # note how the word ``priority'' here has a general meaning:
+    # it indicates every process than can bubble up the sorted
+    # ready queue and come before another. So it's up to
+    # Policy.sort_queue() to give it a precise meaning.
+    # 
+    # Should be implemented with signature:
+    # @code
+    # def is_preemptive(self):
+    #      # function body
+    # @endcode
+    #
+    # @return True If the policy declares it wants the running
+    # process to be released if a process at higher priority
+    # is put at the beginning of the ready processes queue
+    # @return False If the policy always waits the end of the time
+    # slice (or a process blocking/termination, of course) before
+    # selecting a new running process, even if it has greater priority
+    # than the current one
+    is_preemptive = AbstractMethod('is_preemptive')
+
+    ## @brief Returns how long is a time-slice for this policy
+    #
+    # A time sliced policy should return a positive integer value,
+    # a policy which doesn't use slices should instead return -1.
+    # You're encouraged to use a user-configurable parameter via
+    # Policy.configure() if the policy is time-sliced, to ensure
+    # greater flexibility.
+    # 
+    # Should be implemented with signature:
+    # @code
+    # def get_time_slice(self):
+    #      # function body
+    # @endcode
+    #
+    # FIXME: what happens for ``return 0''? The same as ``return 1''?
+    #
+    # @return -1 If the policy doesn't want to use time slices
+    # @return 0+ To specify a time slice duration for this policy
+    get_time_slice = AbstractMethod('get_time_slice')
+    
+    ## @brief This function implements an in-place stable sort
+    # using directly SchedulableQueue methods
+    #
+    # The compare parameter should be a user defined binary
+    # function returning either True or False, defined in one
+    # of the following ways:
+    # @code
+    # # As a lambda anonymous function (preferred)
+    # cmpf = lambda x,y: x.someProperty() < y.someProperty()
+    #
+    # # As a normal *global* function
+    # def compare(a,b):
+    #     return a.someProperty < b.someProperty()
+    # cmpf = compare
+    # @endcode
+    #
+    # The call is then simply:
+    # @code
+    # def sort_queue() :
+    #     # ...
+    #     self.sort(queue, cmpf)
+    # @endcode
+    #
+    # @param self The object caller
     # @param queue The SchedulableQueue to be sorted in place
     # @param cmpf The binary function to use to compare elements
     # @returns None