essageAdded chapter Writing new policies

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

doc/sgpem2uman.texi

@@ -86,7 +86,8 @@ Free Documentation License''.
 @unnumbered History
 
 @table @strong
-
+@item 2006, March 10th @r{--- Djina Verbanac}
+Added chapter Writing new policies
 @item 2006, March 9th @r{--- Djina Verbanac}
 Add chapters Overview of SGPEM and Starting with SGPEM.
 @item 2006, January 26th @r{--- Matteo Settenvini}
@@ -127,8 +128,7 @@ in un Elaboratore Multiprogrammato}'' (in English, ``@emph{Multitasking Computer
 Management Simulator}'').
 It was initially developed for use inside the ``Operating Systems'' teaching,
 part of the Computer Science course of the University of Padova, Italy. 
-
+The aim of SGPEM is to provide an  for simulating policies applied to sort processes, and for assigning resources in a multitasking computer. SGPEMv2 is a didactic software, and it can help students to understand better the functionality of Operating Systems.
-SGPEMv2 is a didactic software, so the main product users are professors and students interested in the simulation of processes.
 
 
 @c % --------------------------------------------------
@@ -362,7 +362,7 @@ install @command{dot}, part of the @emph{Graphviz} package.
 
 @menu
 
-* SGPEM Commands:: Here you find a set of commands available 
+* SGPEM Commands:: Here you'll find a set of commands available 
                         from the command line
 * SGPEM Output:: Interpretation of the output 
 * Writing new policies:: Steps that must be followed to insert a new policy
@@ -380,7 +380,7 @@ install @command{dot}, part of the @emph{Graphviz} package.
 @item help @command{<string>}
 If <string> is a valid command, it prints the usage instructions for that specific command
 @item @command{run}
- Advances the simulation by one or more steps, depending on the actual state and on the value sett ed with setmode
+ Advances the simulation by one or more steps, depending on the actual state and on the value set ed with setmode
 @item @command{pause}
  It is useful only when the advancement mode is continue. Calling again run will cause the simulation to start from the current simulation step.
 @item @command{stop}
@@ -414,13 +414,19 @@ If <string> is a valid command, it prints the usage instructions for that specif
 @section SGPEM Output
 @cindex output
 
-You can seg the textual output of the simulation in your console window or on the GUI window provided with SGPEM v2.
+You can see the textual output of the simulation in your console window or on the GUI window provided with SGPEM v2.
-The output of RUN is one or more rows each of which represents the state of the schedulable entities. 
+The output of RUN gives you one or more rows, each one representing the state of schedulable entities. 
-It can be RUNNING, READY, BLOCKED, FUTURE or TERMINATED.
+The possible states are: @emph{RUNNING}, @emph{READY}, @emph{BLOCKED}, @emph{FUTURE} or @emph{TERMINATED}.
-The row begins with the number of the instant described by the following lists of states. 
+The row begins with the number of the instant described by the following lists of states:
-The instant 0 represents the INITIAL STATE during which no process is running. 
+
-The scheduler activity begins at instant 1. Each schedulable entity is represented by its 
+@itemize
-name followed by its priority enclosed between round parenthesis.
+ 
+@item instant 0 - represents the INITIAL STATE during which no process is running. 
+@item instant 1 - the scheduler activity begins. 
+
+@end itemize
+
+Each schedulable entity is represented by its name followed by its priority enclosed between round parenthesis.
 
 @c % ------------------------------------------------
 
@@ -428,6 +434,70 @@ name followed by its priority enclosed between round parenthesis.
 @section Writing new policies
 @cindex policies
 
+All policies are implemented in Python, but don't worry (be happy!). You don't have to be a Python expert to write a new policy.
+We'll explain you how to write a new policy on an simple example of FCFS policy. Now let's start, all you have to do is change the few bold-ed lines, of the following example.
+@sp 1
+
+@example
+01 from Policy import Policy
+02 class fcfs(Policy) :
+03     def __init__(self):
+04         pass;
+ 
+05     def configure(self):
+@strong{06         print 'No options to configure for fcfs'}
+ 
+07     def is_preemptive(self):
+@strong{08         return False}
+ 
+09     def get_time_slice(self):
+@strong{10         return -1}
+ 
+11     def sort_queue(self, event, queue):
+@strong{12         cmpf = lambda a, b: \
+              a.get_schedulable().get_arrival_time() < \
+              b.get_schedulable().get_arrival_time()
+13         self.sort(queue,cmpf)}
+@end example
+@sp 2
+
+
+@itemize
+@item body of @code{def configure(self):} line 06 - Configure policy to initial values. 
+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.
+@sp 1
+@item body of @code{def is_preemptive(self):} line 08 - It says whether the policy wants to be preemptive, other than by normal time slice termination.
+
+The possible return values are:
+ @enumerate 
+@item 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 
+
+@item 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.
+@end enumerate
+ 
+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.
+
+@sp1
+@item body of @code{def get_time_slice(self):} line 10 - 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.
+@sp 1
+@item body of 
+@code{ def sort_queue(self, event, queue):} 
+line 12,13 - Sort ready processes queue. 
+This method is called by the scheduler at each step of the simulation to sort the ready processes queue. 
+
+@end itemize
+
+
 
 @c % -------------------------------------------------
 @c include license text