diff --git a/doc/sgpem2uman.texi b/doc/sgpem2uman.texi index d7e5b05..547ecdb 100644 --- a/doc/sgpem2uman.texi +++ b/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. - -SGPEMv2 is a didactic software, so the main product users are professors and students interested in the simulation of processes. +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. @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{} If 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 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. -The output of RUN is one or more rows each of which represents the state of the schedulable entities. -It can be RUNNING, READY, BLOCKED, FUTURE or TERMINATED. -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 -name followed by its priority enclosed between round parenthesis. +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 gives you one or more rows, each one representing the state of schedulable entities. +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: + +@itemize + +@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