874 lines
28 KiB
Plaintext
874 lines
28 KiB
Plaintext
\input texinfo @c -*-texinfo-*-
|
|
|
|
@c %**start of header
|
|
@setfilename sgpem2uman.info
|
|
@settitle SGPEMv2 User Manual
|
|
@include vers-uman.texi
|
|
@c %**end of header
|
|
|
|
@dircategory SGPEM v2 - A Process Scheduling Simulator
|
|
@direntry
|
|
* Users: (sgpem2uman)Top
|
|
@end direntry
|
|
|
|
@c % --------------------------------------------------
|
|
|
|
@copying
|
|
This is SGPEMv2 User Manual (version @value{VERSION},
|
|
@value{UPDATED}).
|
|
|
|
Copyright @copyright{} 2005-2006 University of Padova, dept. of Pure
|
|
and Applied Mathematics
|
|
|
|
Permission is granted to copy, distribute and/or modify this document
|
|
under the terms of the GNU Free Documentation License, Version 1.2
|
|
or any later version published by the Free Software Foundation;
|
|
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
|
|
Texts. A copy of the license is included in the section entitled ``GNU
|
|
Free Documentation License''.
|
|
@end copying
|
|
|
|
@c % --------------------------------------------------
|
|
|
|
@titlepage
|
|
@title SGPEMv2 User Manual
|
|
@subtitle for version @value{VERSION}, @value{UPDATED}
|
|
@author Filippo Paparella (@email{ironpipp@@gmail.com})
|
|
@author Paolo Santi (@email{psanti@@studenti.math.unipd.it})
|
|
@author Matteo Settenvini (@email{matteo@@member.fsf.org})
|
|
@author Marco Trevisan (@email{evenjn@@gmail.com})
|
|
@author Djina Verbanac (@email{betalgez@@yahoo.com})
|
|
@author Luca Vezzaro (@email{lvezzaro@@studenti.math.unipd.it})
|
|
@page
|
|
@vskip 0pt plus 1filll
|
|
@insertcopying
|
|
@end titlepage
|
|
|
|
@c Output the table of contents at the beginning.
|
|
@contents
|
|
|
|
@c % --------------------------------------------------
|
|
|
|
@c SGPEMv2 User Manual
|
|
|
|
@c % --------------------------------------------------
|
|
|
|
@ifnottex
|
|
@node Top, History, (none), (dir)
|
|
@top Learn how to operate SGPEMv2
|
|
|
|
@insertcopying
|
|
@end ifnottex
|
|
|
|
@menu
|
|
|
|
* History:: The history of changes to this document.
|
|
|
|
* Overview of SGPEM:: Description and objectives of SGPEM v2.
|
|
|
|
* Installation:: Here we explain how to install SGPEM v2,
|
|
as well as providing some advice for
|
|
believed-to-be useful compilation options.
|
|
|
|
* Basics:: Things you should know before starting.
|
|
|
|
* Using SGPEM:: Instructions on how to use SGPEM.
|
|
|
|
* Extending SGPEM:: Learn how to write new policies and plugins.
|
|
|
|
* License:: A full copy of the GNU Free Documentation License
|
|
this manual is licensed into.
|
|
|
|
* Concept index:: Complete index.
|
|
@end menu
|
|
|
|
|
|
@c % --------------------------------------------------
|
|
|
|
@node History, Overview of SGPEM, Top, Top
|
|
@unnumbered History
|
|
|
|
@table @strong
|
|
@item 2006, September 8th @r{-- Matteo Settenvini}
|
|
Update chapters about building and installation. Rewrite some of the
|
|
chapter about extending SGPEMv2 with custom CPU policies, and add a
|
|
more complex example.
|
|
@item 2006, September 7th @r{--- Luca Vezzaro}
|
|
First attempt at expanding the manual structure with the
|
|
stuff we'll need in the forthcoming beta testing
|
|
@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}
|
|
Add subsection about how to generate code documentation
|
|
via Doxygen.
|
|
|
|
@item 2005, December 11th @r{--- Matteo Settenvini}
|
|
Added full license text.
|
|
|
|
@item 2005, November 8th @r{--- Matteo Settenvini}
|
|
First draft of this document.
|
|
|
|
@end table
|
|
|
|
|
|
@c % --------------------------------------------------
|
|
|
|
@node Overview of SGPEM, Installation, History, Top
|
|
@chapter Overview of SGPEM
|
|
|
|
|
|
@menu
|
|
* Description and aims::
|
|
* How to read this manual?::
|
|
* Reporting Bugs::
|
|
* Features::
|
|
@end menu
|
|
|
|
@c % --------------------------------------------------
|
|
|
|
@node Description and aims, How to read this manual?, Overview of SGPEM, Overview of SGPEM
|
|
@section Description and aims
|
|
@cindex SGPEM
|
|
@cindex description
|
|
|
|
SGPEM is an Italian acronym, standing for ``@emph{Simulatore della Gestione dei Processi
|
|
in un Elaboratore Multiprogrammato}'' (in English, ``@emph{Process
|
|
Management Simulator for a Multitasking Computer}'').
|
|
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 easy-to-use environment for
|
|
simulating process scheduling policies, and for assigning resources in
|
|
a multitasking computer. SGPEMv2 is an educational software, and it can
|
|
help students to better understand the functionality of operating systems.
|
|
|
|
|
|
@c % --------------------------------------------------
|
|
|
|
@node How to read this manual?, Reporting Bugs, Description and aims, Overview of SGPEM
|
|
@section How to read this manual?
|
|
@cindex manual
|
|
|
|
We recommend that you read the manual following the the structure that
|
|
we layed out for it. You will be gently led trough Installation, Configuration and Usage of SGPEMv2.
|
|
If you find yourself in trouble reading the manual, please don't hesitate to contact us at
|
|
@email{swe@@thgnet.it}.
|
|
|
|
@c % --------------------------------------------------
|
|
|
|
@node Reporting Bugs,Features, How to read this manual?, Overview of SGPEM
|
|
@section Reporting Bugs
|
|
@cindex bugs
|
|
@cindex reporting
|
|
|
|
We welcome bug reports and suggestions for any aspect of the SGPEM v2 system, program in general,
|
|
documentation, installation... anything. Please email us at @email{swe@@thgnet.it}.
|
|
For bug reporters, include enough information for us to reproduce the problem. In general:
|
|
@itemize
|
|
@item
|
|
version and number of SGPEM v2.
|
|
@item
|
|
hardware and operating system name and version.
|
|
@item
|
|
the content of any file neccesary to reproduce the bug.
|
|
@item
|
|
description of the problem and any erroneous output.
|
|
@item
|
|
any unusual option you gave to configure.
|
|
@item
|
|
anything else you think might be helpful.
|
|
@end itemize
|
|
If you are ambitious you can try to fix the problem yourself, but we warmly recommend that you read the
|
|
Developer Manual first.
|
|
|
|
|
|
@c % --------------------------------------------------
|
|
|
|
|
|
@node Features, (none), Reporting Bugs, Overview of SGPEM
|
|
@section Features
|
|
@cindex features
|
|
|
|
Main features are:
|
|
@itemize
|
|
@item
|
|
For now you can use only prompt commands to start the simulation and change some parameters.
|
|
For more information see @ref{SGPEM Commands}.
|
|
@item
|
|
You can use the program from your own shell, or if you prefer you can use the minimal GUI that SGPEM offers, at this moment.
|
|
@item
|
|
The output of the simulation is textual, and you can see it on the main GUI window or on your Terminal window.
|
|
@item
|
|
The policy in use is First Come First Served.
|
|
@item
|
|
You can write your own policies.
|
|
For more information see @ref{Writing new policies}.
|
|
@end itemize
|
|
|
|
|
|
@c % --------------------------------------------------
|
|
|
|
@node Installation, Basics, Overview of SGPEM, Top
|
|
@chapter Installation
|
|
@cindex installation
|
|
|
|
@menu
|
|
* Prerequisites:: Programs and libraries needed to
|
|
compile and run SGPEM
|
|
|
|
* Building:: Help for compiling SGPEM on
|
|
your platform.
|
|
|
|
@end menu
|
|
|
|
@c % --------------------------------------------------
|
|
|
|
@node Prerequisites, Building, Installation, Installation
|
|
@section Prerequisites
|
|
@cindex requirements
|
|
|
|
Some software is needed in order to build and install SGPEM on your
|
|
personal computer. You will have the need of different pieces of
|
|
software installed, whether you are a developer, a user building it
|
|
from sources, or just a user that's running the binary a packager
|
|
has given to him.
|
|
|
|
And if you find this section misses something / it lists
|
|
the wrong version of a program, please let us know!
|
|
|
|
@c % ---- new subsection
|
|
@subsection Runtime dependencies
|
|
|
|
To run SGPEMv2, you require:
|
|
|
|
@table @emph
|
|
|
|
@item Gtkmm >= 2.8 with Cairo support
|
|
The popular C++ jacket for the even-more popular GIMP
|
|
ToolKit. We use Cairo to draw our custom widgets.
|
|
|
|
@item Python >= 2.3
|
|
We use Python to let the user write her own policies
|
|
in a simple and complete language.
|
|
|
|
@item libXML2 >= 2.6.10
|
|
An XML library we use to save and load files to/from disk.
|
|
|
|
@end table
|
|
|
|
@c % ---- new subsection
|
|
@subsection Building from source
|
|
|
|
Other than the runtime dependencies, you'll need:
|
|
|
|
@table @emph
|
|
|
|
@item SWIG >= 1.3.21
|
|
SWIG generates the C++ sources needed to build a module that
|
|
Python can use, starting from a simple interface specification.
|
|
|
|
@end table
|
|
|
|
@c % ---- new subsection
|
|
@subsection Developers
|
|
|
|
Other than the tools needed by users building from sources,
|
|
you'll need:
|
|
|
|
@table @emph
|
|
@item GCC with C++ support
|
|
as well as the other standard GNU binutils and tools: make, sed, ld...
|
|
GCC version >=3.4 is highly recommended. Please don't report
|
|
compiling-related problems with any previous version. There are some
|
|
known issues with certain versions of GCC 4.0. @xref{Building}.
|
|
|
|
@item Automake >= 1.9
|
|
We use a single @file{Makefile.am} to avoid
|
|
recursive make. Older versions of automake didn't play right
|
|
with it. See @url{http://aegis.sourceforge.net/@/auug97.pdf} for
|
|
the motivations that led to this choice.
|
|
|
|
@item Autoconf, libtool, autopoint @dots{}
|
|
The standard autotool family.
|
|
|
|
@item Subversion >= 1.2
|
|
If you need to update the sources from our repository, or commit
|
|
your changes, you'll need Subversion built with SSL support.
|
|
|
|
@item Dejagnu >= 1.4
|
|
The testsuite framework we use as a platform for running tests.
|
|
|
|
@end table
|
|
|
|
@c % --------------------------------------------------
|
|
|
|
@node Building, (none), Prerequisites, Installation
|
|
@section Building
|
|
@cindex compiling
|
|
|
|
@noindent To ensure a clean build, follow these steps:
|
|
|
|
@sp 1
|
|
@example
|
|
@code{cd <the package root directory>}
|
|
@code{mkdir =build}
|
|
@code{cd =build}
|
|
@code{CXXFLAGS="what you want" ../configure --prefix=/usr/local}
|
|
@end example
|
|
@sp 1
|
|
|
|
@noindent This will check you have all the needed software installed.
|
|
|
|
@noindent Choose good @env{CXXFLAGS} to optimize your build.
|
|
For example, on my machine, I would use:
|
|
|
|
@sp 1
|
|
@example
|
|
@code{CXXFLAGS="-O3 -pipe -march=pentium4" ../configure --prefix=/usr/local}
|
|
@end example
|
|
@sp 1
|
|
|
|
@noindent Being a developer, though, if I had to debug SGPEM, I would
|
|
type:
|
|
|
|
@sp 1
|
|
@example
|
|
@code{../configure --prefix=`pwd`/../=inst --enable-debug}
|
|
@end example
|
|
@sp 1
|
|
|
|
@noindent Please note that those around ``pwd'' are backticks, and not
|
|
normal apostrophes.
|
|
|
|
@strong{Warning}: at the moment, we are aware that passing
|
|
@option{--disable-shared} to configure doesn't work. We'll look into it
|
|
sooner or later, but in the meantime just build shared libraries.
|
|
|
|
@noindent Once succesfully configured SGPEMv2, just type:
|
|
|
|
@sp 1
|
|
@example
|
|
@command{make}
|
|
@end example
|
|
@sp 1
|
|
|
|
@noindent Some versions of GCC 4, usually those before the 4.1 series,
|
|
present some problems with the newly-added visibility support for DSO
|
|
object symbols. For example, OpenSuSE 10.0 is known to have such
|
|
issues. If you encounter problems during building and in linking stage
|
|
about unresolved symbols in libraries, please re-run
|
|
@command{configure} with the @option{--disable-visibility-support}
|
|
option. You'll then have to run @command{make clean && make}.
|
|
|
|
|
|
@noindent Upon a succesful build, you can install SGPEMv2 just by hitting:
|
|
|
|
@sp 1
|
|
@example
|
|
@code{su -c "make install"}
|
|
@end example
|
|
@sp 1
|
|
|
|
@noindent Root password will be required (of course, if you're
|
|
installing it with a prefix placed inside your home directory,
|
|
you won't need administrative rights, and just ``@command{make install}''
|
|
will sufficit).
|
|
|
|
See the ``@file{INSTALL}'' file in this folder for an overview of other
|
|
(less common) autoconf options.
|
|
|
|
@subsection Generating API documentation
|
|
|
|
We added Doxygen support to the project. If you've installed it,
|
|
you can simply run @command{make apidox} from the package
|
|
top source directory. The documentation will be outputted into
|
|
the @samp{$@{BUILD_DIR@}/docs/API/} dir.
|
|
|
|
If you'd like to generate nicier inheritance graphs, you've just to
|
|
install @command{dot}, part of the @emph{Graphviz} package. If you
|
|
didn't have it previously installed, you may need to re-run @command{configure}.
|
|
|
|
@c % --------------------------------------------------
|
|
|
|
|
|
@node Basics, Using SGPEM, Installation, Top
|
|
@chapter Basics
|
|
@cindex basics
|
|
|
|
@menu
|
|
|
|
* Policies:: Everything you'll ever wanted to know about policies
|
|
in SGPEM!
|
|
* The Scheduler:: Essential background information necessary to
|
|
understand how schedulable entities are scheduled.
|
|
|
|
@end menu
|
|
|
|
@c % -------------------------------------------------
|
|
@node Policies, The Scheduler, Basics, Basics
|
|
@section Policies
|
|
@cindex policies
|
|
|
|
@menu
|
|
|
|
* What is a policy in SGPEM?:: Explains what a SGPEM policy can, should and must do,
|
|
and what it can't do. And how.
|
|
* What kind of policies are there?:: In SGPEM there a two very different
|
|
kinds of policies. This subsection explains
|
|
these differences.
|
|
* Built-in policies:: Here you will find a detailed descriptions of the policies
|
|
shipped with the standard distribution of SGPEM.
|
|
|
|
@end menu
|
|
|
|
@node What is a policy in SGPEM?, What kind of policies are there?, Policies, Policies
|
|
@subsection What is a policy in SGPEM?
|
|
@cindex policies basics
|
|
|
|
@node What kind of policies are there?, Built-in policies, What is a policy in SGPEM?, Policies
|
|
@subsection What kind of policies are there?
|
|
@cindex policies kinds
|
|
|
|
@node Built-in policies, (none), What kind of policies are there?, Policies
|
|
@subsection Built-in policies
|
|
@cindex built-in policies
|
|
|
|
@c % -------------------------------------------------
|
|
@node The Scheduler, (none), Policies, Basics
|
|
@section The Scheduler
|
|
@cindex scheduler basics
|
|
|
|
|
|
@c % --------------------------------------------------
|
|
|
|
@node Using SGPEM, Extending SGPEM, Basics, Top
|
|
@chapter Using SGPEM
|
|
@cindex using
|
|
|
|
@menu
|
|
|
|
* From the GUI::
|
|
* From the commandline::
|
|
|
|
@end menu
|
|
|
|
@c % -------------------------------------------------
|
|
@node From the GUI, From the commandline, Using SGPEM, Using SGPEM
|
|
@section From the GUI
|
|
@cindex GUI
|
|
|
|
@menu
|
|
* Overall view of the main window::
|
|
* The Schedulables/Requests tree::
|
|
* The Resources list::
|
|
* The Simulation widget::
|
|
* The Holt graph::
|
|
* The Preferences dialog::
|
|
* Controlling the simulation:: This subsection will explain you all the means
|
|
available to control the simulation workflow.
|
|
@end menu
|
|
|
|
@c % -------------------------------------------------
|
|
@node Overall view of the main window, The Schedulables/Requests tree, From the GUI, From the GUI
|
|
@subsection Overall view of the main window
|
|
@cindex main window
|
|
|
|
@image{main-window,18cm,13.5cm,Screenshot of the main window during a simulation}
|
|
|
|
Blah blah blah...
|
|
|
|
@c % -------------------------------------------------
|
|
@node The Schedulables/Requests tree, The Resources list, Overall view of the main window, From the GUI
|
|
@subsection The Schedulables/Requests tree
|
|
@cindex schedulables tree
|
|
|
|
@c % -------------------------------------------------
|
|
@node The Resources list, The Simulation widget, The Schedulables/Requests tree, From the GUI
|
|
@subsection The Resources list
|
|
@cindex resources
|
|
|
|
@c % -------------------------------------------------
|
|
@node The Simulation widget, The Holt graph, The Resources list, From the GUI
|
|
@subsection The Simulation widget
|
|
@cindex simulation widget
|
|
|
|
@c % -------------------------------------------------
|
|
@node The Holt graph, The Preferences dialog, The Simulation widget, From the GUI
|
|
@subsection The Holt graph
|
|
@cindex holt
|
|
|
|
@c % -------------------------------------------------
|
|
@node The Preferences dialog, Controlling the simulation, The Holt graph, From the GUI
|
|
@subsection The Preferences dialog
|
|
@cindex preferences
|
|
|
|
@c % -------------------------------------------------
|
|
@node Controlling the simulation, (none), The Preferences dialog, From the GUI
|
|
@subsection Controlling the simulation
|
|
@cindex simulation
|
|
|
|
|
|
@c % -------------------------------------------------
|
|
@node From the commandline, (none), From the GUI, Using SGPEM
|
|
@section From the commandline
|
|
@cindex commandline
|
|
|
|
@menu
|
|
|
|
* SGPEM Commands:: Here you'll find a set of commands available
|
|
from the command line
|
|
* SGPEM Output:: Interpretation of the output
|
|
|
|
@end menu
|
|
|
|
@c % -------------------------------------------------
|
|
@node SGPEM Commands, SGPEM Output, From the commandline, From the commandline
|
|
@subsection SGPEM Commands
|
|
@cindex commands
|
|
|
|
|
|
@table @strong
|
|
|
|
@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 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}
|
|
Stops the simulation.
|
|
@item @command{setmode <bool>}
|
|
This methods allows to change the way the simulation progresses. If the input value is 0 (false), the simulation will advance a single time step for each call to run. If the
|
|
input value is 1 (true), the simulation will advance contiuosly, waiting the time defined with settimer between each step, until all processes terminate,
|
|
or some error occurs.
|
|
@item @command{getmode}
|
|
Prints the simulation advancement mode: 0 if step-to-step, 1 if continue.
|
|
@item @command{settimer <int>}
|
|
This command is used to define how a single time unit is to be interpreted when the simulation advancement mode is continue.
|
|
The input value is in milliseconds, and it must be in range [0, 10000].
|
|
@item @command{gettimer}
|
|
Prints the value of the current timer
|
|
@item @command{reset}
|
|
Resets the simulation.Erases the state of the simulation, and takes care of removing any residual or temporary data to ensure the simulation has reached
|
|
a clean and stable state.
|
|
@item @command{jumpto <int>}
|
|
Causes the simulation to jump to a given time unit.
|
|
@item @command{getpolicy}
|
|
Prints the current policy.
|
|
@item @command{getpolicyattributes}
|
|
Prints the name and the value of the policy's attributes
|
|
|
|
@end table
|
|
|
|
@c % -------------------------------------------------
|
|
|
|
@node SGPEM Output, (none), SGPEM Commands, From the commandline
|
|
@subsection SGPEM Output
|
|
@cindex output
|
|
|
|
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 % ------------------------------------------------
|
|
|
|
@node Extending SGPEM, License, Using SGPEM, Top
|
|
@chapter Extending SGPEM
|
|
@cindex extending
|
|
|
|
@menu
|
|
|
|
* Writing new policies:: Steps that must be followed to insert a new policy
|
|
* Writing plugins::
|
|
|
|
@end menu
|
|
|
|
@c % -------------------------------------------------
|
|
|
|
@node Writing new policies, Writing plugins, Extending SGPEM, Extending SGPEM
|
|
@section Writing new policies
|
|
@cindex writing policies
|
|
|
|
All built-in policies are implemented in Python, but don't worry: 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. Then a more complex example will follow: a Round Robin policy
|
|
that uses pre-emption by priority.
|
|
|
|
Now let's get started, all you have to do to create your own policy is
|
|
to change the few bold lines of the following example. Also remember
|
|
that the name of the class have to be the same of the name of the file
|
|
(minus the @code{.py} file extension, of course).
|
|
|
|
|
|
|
|
@c % --------- new subsection
|
|
@subsection A beginner example: First Come First Served
|
|
|
|
@example
|
|
01 from CPUPolicy import CPUPolicy
|
|
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
|
|
|
|
|
|
@table @asis
|
|
@item body of @code{def configure(self)}: line 06
|
|
|
|
Configure policy to initial values. This is called just before a
|
|
simulation starts, and it is responsible to define
|
|
the parameters the policy wants to expose to the user. For example, it may make
|
|
the return value returned by @code{is_preemptive()} configurable, or
|
|
to register an integer value for a the time slice duration.
|
|
|
|
@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 (if a positive time slice has been provided).
|
|
|
|
The possible return values are:
|
|
@enumerate
|
|
|
|
@item
|
|
@code{True}: If the policy returns True, it declares that it wants the running
|
|
thread to be released if a thread at higher priority is put at the
|
|
beginning of the ready threads queue.
|
|
|
|
This is achieved by putting the current running thread, if there is
|
|
one, onto the ready queue. It is up to you, into the
|
|
@code{sort_queue()} method, to manage this special case.
|
|
|
|
@item
|
|
@code{False}: The policy always waits the end of the time slice (or a thread
|
|
blocking/termination) before selecting a new running thread, even if it
|
|
has greater priority than the current one.
|
|
|
|
There will never be a running thread in the ready queue passed to
|
|
@code{sort_queue()}.
|
|
|
|
@end enumerate
|
|
|
|
Please note how the word ``priority'' here has a general meaning: it indicates every thread 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.
|
|
|
|
@sp 1
|
|
@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 @code{-1}. You're encouraged to use a user-configurable
|
|
parameter via @code{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 the queue of ready threads. This method is called by the
|
|
scheduler at each step of the simulation to sort the ready threads
|
|
queue. It is the core of your policy: when scheduler has to select
|
|
a new thread it will always try to take the first of the queue. If it
|
|
cannot run for some reason (for example, it immediately blocks), the
|
|
second is selected and so on, until the end of the queue.
|
|
|
|
Remember that if @code{is_preemptible()} returns True, you may have
|
|
a running thread in the queue. See the following example for some tips
|
|
about how to manage this case.
|
|
|
|
Pay attention to the fact that we used the @code{<=} relation at line @samp{12}, and
|
|
not a simple @code{<}. This is because @code{queue.sort()} uses a
|
|
in-place implementation of quicksort, which is stable only when
|
|
employed with a minor-or-equal relation. Otherwise the queue would be
|
|
sorted, but two adjacent threads that have the same value for a given
|
|
priority would be swapped. If your policy behaves strangely, this may
|
|
be the cause.
|
|
|
|
@end table
|
|
|
|
@c % --------- new subsection
|
|
@subsection Exposed interface: what you can use
|
|
|
|
@anchor{Configuring parameters}
|
|
@subsubsection Configuring parameters
|
|
|
|
TODO: list and describe all methods exposed from PolicyParameters.
|
|
|
|
@subsubsection Methods for manipulating the ready queue
|
|
|
|
TODO: list and describe all methods exposed from ReadyQueue.
|
|
|
|
@subsubsection Properties of schedulable entities
|
|
|
|
TODO: list and describe all methods exposed from Schedulable,
|
|
Thread and Process
|
|
|
|
|
|
@c % --------- new subsection
|
|
@subsection A more complete example: Round Robin with priority
|
|
|
|
Now, let's see a more interesting (and a little more complex) example:
|
|
a Round Robin by priority policy that can optionally also work with
|
|
pre-emption by priority.
|
|
|
|
@sp 2
|
|
@example
|
|
00 from CPUPolicy import CPUPolicy
|
|
01
|
|
02 class rr_priority(CPUPolicy) :
|
|
03 """Round Robin scheduling policy that takes priority in account.
|
|
04
|
|
05 No lower priority thread can run if a higher
|
|
06 priority thread exists. If pre-emptive by priority, a
|
|
07 higher-priority thread becoming ready even in the middle
|
|
08 of a time slice will pre-empt the running thread. Else,
|
|
09 the time slice will have to end before the former can run."""
|
|
10
|
|
11 def __init__(self):
|
|
12 pass;
|
|
13
|
|
14 def configure(self):
|
|
15 param = self.get_parameters()
|
|
16 param.register_int("Time slice", 1, 10000, True, 2)
|
|
17 param.register_int("Is preemptive?", 0, 1, True, 1)
|
|
18
|
|
19 def is_preemptive(self):
|
|
20 value = self.get_parameters().get_int("Is preemptive?")
|
|
21 if value == 0:
|
|
22 return False
|
|
23 else:
|
|
24 return True
|
|
25
|
|
26 def get_time_slice(self):
|
|
27 return self.get_parameters().get_int("Time slice")
|
|
28
|
|
29 def sort_queue(self, queue):
|
|
30 by_ltime = lambda a, b: \
|
|
31 a.get_last_acquisition() <= \
|
|
32 b.get_last_acquisition()
|
|
33 by_prio = lambda a, b: \
|
|
34 a.get_current_priority() <= \
|
|
35 b.get_current_priority()
|
|
36
|
|
37 self.sort(queue,by_ltime)
|
|
38 self.sort(queue,by_prio)
|
|
39
|
|
40 # manage preemption: see if we've a running thread
|
|
41 # in the ready queue, and if it can still run
|
|
42 if self.is_preemptive() == True:
|
|
43 higher_prio = queue.get_item_at(0).get_current_priority()
|
|
44 i = 0
|
|
45 while i < queue.size():
|
|
46 sched = queue.get_item_at(i)
|
|
47 priority = sched.get_current_priority()
|
|
48 if(priority != higher_prio):
|
|
49 break
|
|
50 if sched.get_state() == "running":
|
|
51 queue.bubble_to_front(i)
|
|
52 i += 1
|
|
@end example
|
|
|
|
We've also added a description of the class immediately
|
|
following the class declaration (lines @samp{03-09}). This is what is
|
|
returned as the policy description in the frontend. You may want to
|
|
document your policies in the same way too.
|
|
|
|
Now, let's see the most complex parts together:
|
|
|
|
@table @code
|
|
@item configure()
|
|
|
|
There are three types of parameters you can register in the value
|
|
returned by @code{self.get_parameters()}, and they are integer
|
|
parameters, float parameters and strings. Usually boolean values can
|
|
be simulated by registering a integer parameter limited in the
|
|
interval [0, 1]. @xref{Configuring parameters} for the exposed interface.
|
|
|
|
@item is_preemptive()
|
|
|
|
TODO: write me
|
|
|
|
@item sort_queue()
|
|
|
|
Here there are quite a lot of things going on, so let's tackle them
|
|
one by one.
|
|
|
|
At line @samp{30} we create a lambda-function that says to sort the queue
|
|
by last aquisition time, so that threads that have been aquired
|
|
recently end up at the back of the queue (which is exactly what a
|
|
Round Robin policy should do).
|
|
|
|
Then, at line @samp{33}, we create another lambda-function, this time
|
|
because we want to sort the queue by priority, too.
|
|
|
|
Done this, we let quicksort do the hard job at lines @samp{37-38}.
|
|
|
|
Since we may have pre-emption enabled, we may have a running thread on
|
|
the ready queue (if one exists at the current instant). But what
|
|
happens if the running thread was put in the queue, and we just sorted it?
|
|
|
|
Unfortunately, having the greatest last aquisition time, the running thread would end
|
|
at the back of the queue, thus never being selected to run for more
|
|
than a single time unit if the queue is non-empty and there are other
|
|
threads with the same priority!
|
|
|
|
The solution is to check if there is a thread with state ``running''
|
|
at the beginning of the queue, between those that have the same
|
|
priority. If there's one, we make it bubble to the top of the queue.
|
|
|
|
This is the explanation for lines @samp{42-52}.
|
|
|
|
@end table
|
|
|
|
|
|
@c % -------------------------------------------------
|
|
|
|
@node Writing plugins, (none), Writing new policies, Extending SGPEM
|
|
@section Writing plugins
|
|
@cindex plugins
|
|
|
|
TODO: write me
|
|
|
|
@c % -------------------------------------------------
|
|
@c include license text
|
|
@node License, Concept index, Extending SGPEM, Top
|
|
@include fdl.texi
|
|
|
|
@c % --------------------------------------------------
|
|
|
|
@node Concept index, (none), License, Top
|
|
@unnumbered Index
|
|
|
|
@printindex cp
|
|
|
|
@bye
|
|
|