- Update manuals with:

* exposed interface
  * scheduling policies description


git-svn-id: svn://svn.gna.org/svn/sgpemv2/trunk@1071 3ecf2c5c-341e-0410-92b4-d18e462d057c
This commit is contained in:
tchernobog 2006-09-08 20:55:19 +00:00
parent 34825da69b
commit 461f29023e
2 changed files with 265 additions and 19 deletions

View File

@ -80,6 +80,9 @@ Free Documentation License''.
* Using the Mailing List:: How to compose your messages
when contacting us on the ML
* Writing your own plugins:: How to extend SGPEMv2 with
additional functionalities
* License:: The full text of the license under which this
manual is given to you
@ -298,7 +301,7 @@ documents or resources.
Other parts of the document are specific to the technical document
itself, and therefore should be managed by the editor.
Mostly, the general structure for the more common documents can be found at
@uref{http://www.math.unipd.it/~tullio/IS-1/2005/Progetto/Documenti.html}
@uref{http://www.math.unipd.it/@/~tullio/@/IS-1/@/2005/@/Progetto/@/Documenti.html}
(in Italian).
In the @samp{docs/misc/} directory of the Subversion repository,
@ -361,7 +364,7 @@ In order to generate documentation straight from the source code:
@cindex documenting C++ code
Please refer to @emph{Doxygen} manual
(@uref{http://www.stack.nl/~dimitri/doxygen/manual.html})
(@uref{http://www.stack.nl/@/~dimitri/@/doxygen/@/manual.html})
in order to learn how to use this automatic tool for extracting
documentation from code.
@ -386,7 +389,7 @@ to learn more of it.
However, if we want to generate good documentation straight
from code, with the help of Doxygen, we should use the @samp{#}
documenting style. Please look at the end of
@uref{http://www.stack.nl/~dimitri/doxygen/docblocks.html} for
@uref{http://www.stack.nl/@/~dimitri/@/doxygen/@/docblocks.html} for
an example.
@c % ----- new subsection
@ -1102,7 +1105,7 @@ Never use global static variables of non-POD (Plain Old Data)
type.
The reason why not doing this is fundamental, and it is well
described, along with a possible alternative here:
@url{http://www.parashift.com/c++-faq-lite/ctors.html#faq-10.12}.
@url{http://www.parashift.com/@/c++-faq-lite/@/ctors.html#faq-10.12}.
@end enumerate
@ -1370,7 +1373,7 @@ practice, locking seems to inhibit productivity more than anything else.
@c % --------------------------------------------------
@node Using the Mailing List, License, Committing changes, Top
@node Using the Mailing List, Writing your own plugins, Committing changes, Top
@chapter Using the Mailing List
@cindex mailing list
@ -1550,7 +1553,15 @@ Have fun, and ...
@c % --------------------------------------------------
@c include license text
@node License, Concept index, Using the Mailing List, Top
@node Writing your own plugins, License, Using the Mailing List, Top
@chapter Writing your own plugins
TODO: write me.
@c % --------------------------------------------------
@c include license text
@node License, Concept index, Writing your own plugins, Top
@include fdl.texi
@c % --------------------------------------------------

View File

@ -92,7 +92,8 @@ Free Documentation License''.
@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.
more complex example. Document interfaces exported to Python.
Quickly describe built-in scheduling policies.
@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
@ -426,6 +427,10 @@ didn't have it previously installed, you may need to re-run @command{configure}.
@subsection What is a policy in SGPEM?
@cindex policies basics
TODO: remember to say that we schedule threads, not processes, and
that if you want to schedule processes just put into them one single
thread and choose to hide threads from the GUI.
@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
@ -434,6 +439,71 @@ didn't have it previously installed, you may need to re-run @command{configure}.
@subsection Built-in policies
@cindex built-in policies
@subsubsection CPU scheduling policies
@table @asis
@item FCFS: First come first served
The first thread to arrive to the CPU will run until
it ends. This policy never pre-empts; it is probably
the simplest of them all.
This policy has no options to configure, too.
@item SJF: Shortest job first
The thread with the shortest required CPU time
will run until it ends. If @samp{Is pre-emptive?}
is set to true (@samp{1}), given that a thread requiring
less than the remaining time of the current running
thread arrives at the CPU, the latter will
pre-empt the former.
In this case, the policy is also called ``Shortest Remaining
Time Next''.
You can configure if you want this policy to be pre-emptive
or not.
@item RR: Round Robin
This policy executes a thread for a given amount
of time (the time-slice value), and then puts it
at the end of the queue. It does not pre-empt before
the end of the time slice, since it doesn't take
priority in account. Use ``RR priority'' for that.
You can configure the duration of the time slice.
@item RR priority
No lower priority thread can run if a higher
priority thread exists. If pre-emptive by priority, a
higher-priority thread becoming ready, even in the middle
of a time slice, will pre-empt the running thread. Else,
the time slice will have to end before the higher-priority
thread can run.
You can configure if this policy is preemptive or not,
and the duration of the time slice.
@item Lottery scheduling
Every time slice, a thread will be selected from the ready
queue by random. This policy does not pre-empt before the
end of the time slice.
@end table
@subsubsection Resource scheduling policies
TODO: write me!
@table @asis
@end table
@c % -------------------------------------------------
@node The Scheduler, (none), Policies, Basics
@section The Scheduler
@ -476,7 +546,38 @@ didn't have it previously installed, you may need to re-run @command{configure}.
@image{main-window,18cm,13.5cm,Screenshot of the main window during a simulation}
Blah blah blah...
@strong{TODO}: rework the following part, divide it into each separate
subsection, and expand it (in English!). This is meant just as a guideline.
Di seguito trovate una sommaria descrizione delle parti piu' importanti
della finestra principale del programma. Una descrizione piu' completa
dovrebbe (o dovra') trovarsi nel manuale utente, ``sgpemv2uman'' (se
volete il PDF, potete generarlo con ``make pdf'' dopo aver configurato i
sorgenti).
Appena sotto ai menu, c'e' la barra degli strumenti. La maggior parte
dei pulsanti ivi contenuta è di immediata comprensione; il menu a
tendina a fianco di ``Scheduling policy'' permette di selezionare una
politica di schedulazione dei thread, e analogamente avviene per
``Resource scheduling''.
Facendo invece clic con il mouse sui pulsanti stessi, si apre una
finestra che descrive la politica e permette di configurarne i
parametri resi disponibili da chi l'ha scritta.
Appena sotto la barra degli strumenti, si trova collocata una doppia
vista; e' quella degli Schedulabili e quella delle Risorse.
Potete aggiungere, togliere, o modificare ciascuna voce attraverso il
menu a comparsa che appare facendo clic con il tastro destro del mouse
su queste aree. Per maggiori informazioni sul significato di ciascuna
entita', e dei loro parametri, si rimanda al manuale utente.
Lo spazio maggiore della finestra è occupato dal widget che visualizza
lo stato della simulazione.
Una finestra modale, nascondibile/visualizzabile tramite il menu View,
mostra il grafo di Holt, che mostra lo stato dell'allocazione delle
risorse. Ridimensionare questa finestra in modo non proporzionale
cambia la modalità di visualizzazione del grafo.
@c % -------------------------------------------------
@node The Schedulables/Requests tree, The Resources list, Overall view of the main window, From the GUI
@ -704,33 +805,165 @@ 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.
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.
@xref{ReadyQueue.sort_queue()}. If your policy behaves strangely,
this may be the cause.
@end table
@c % --------- new subsection
@subsection Exposed interface: what you can use
This is a list of exported interfaces that you can use from
your policy script to manipulate SGPEMv2 exported objects.
If you want to see what methods a Python object exports, remember
that you can also use the built-in @code{dir()} Python function.
@c % --- new subsubsection
@anchor{Configuring parameters}
@subsubsection Configuring parameters
TODO: list and describe all methods exposed from PolicyParameters.
In the meantime, see the example below about the RR policy with priority.
@c % --- new subsubsection
@subsubsection Methods for manipulating the ready queue
TODO: list and describe all methods exposed from ReadyQueue.
The parameter @code{queue} passed to @code{CPUPolicy.sort_queue()}
is of type @code{ReadyQueue}. This is a description of the available
methods:
@table @code
@anchor{ReadyQueue.sort_queue()}
@item ReadyQueue.sort_queue(queue, compare_function)
This is the function that actually does the sorting
of the queue for you. You can of course avoid to call this
method and sort the queue by hand (the ``lottery'' policy
for example doesn't call it).
It takes two parameters: the first is the queue, and the second is a
compare function. Usually you'll want to use a simple lambda-function
defined in the way you can see in the above and following examples.
Remember that this function will internally use a in-place version of
quicksort, which is a stable sorting algorithm only when employed with
a less-or-equal relation(``@code{<=}'') or a greater-or-equal one
(``@code{>=}''). Otherwise the queue would still be sorted, but two
adjacent threads that have the same value for a given property would
be swapped. This might be indesiderable with certain policies, and
could lead to unexpected results, so be careful.
@item ReadyQueue.size()
Returns the number of elements in the queue.
@item ReadyQueue.get_item_at(position)
Returns the thread contained at the given position of the queue, where
@code{0} means the front, and @code{queue.size() - 1} means the last
element (the back) of the queue. Trying to access an element outside
the range [0, queue size) will raise an exception.
@item ReadyQueue.bubble_to_front(position)
Moves the item at the given position up in the queue until
it reaches the front, preserving the order of the other threads.
Trying to access an element outside the range [0, queue size) will
throw an exception at you.
@item ReadyQueue.swap(position_a, position_b)
Swaps the element in position a with the element in position b.
This is used mainly by the internal quicksort implementation, but
you may want to employ it directly in some cases, too.
As you may have already guessed, trying to access an element
outside of the queue will raise an exception.
@end table
@c % --- new subsubsection
@subsubsection Properties of schedulable entities
TODO: list and describe all methods exposed from Schedulable,
Thread and Process
All schedulables, both threads and processes, implement the following methods:
@table @code
@item get_arrival_time()
Returns the time a schedulable arrives to the CPU. For a thread, it is
relative to the time his parent process is spawned. For a process, it
is the absolute time value.
So, a thread will arrive to the CPU after @code{get_arrival_time() +
get_process().get_arrival_time()} units.
@item get_elapsed_time()
Returns for how many time units a schedulable has been running up until now.
@item get_last_acquisition()
Returns the last time a schedulable has been selected for scheduling (that
is, to become the running one).
@item get_last_release()
Returns the last time a schedulable had stopped being scheduled as a
running and has been preempted. Note that this also happens every time
a time-slice ends.
@item get_base_priority()
Returns the priority a schedulable has been spawned with.
@item get_current_priority()
Returns the current priority. It is usually given by
@code{get_base_priority() + priority_push}. See below.
@item set_priority_push(new_value = 0)
Sets the priority push to change the base priority of a
schedulable. It is the only method available that changes
the state of a schedulable.
@item get_total_cpu_time()
Returns the time a schedulable will run before terminating.
@item get_state()
Returns a string describing the state of a schedulable. It can be:
@enumerate
@item ``future''
@item ``ready''
@item ``running''
@item ``blocked''
@item ``terminated''
@end enumerate
@item get_name()
Returns a string with the name the user gave to the schedulable.
@end table
@sp 2
Class @code{Thread} has another method, which is @code{get_process()}. It
returns the father process. Class @code{Process} behaves similarly by
providing a @code{get_threads()} method that returns a list of
children threads.
@c % --------- new subsection
@subsection A more complete example: Round Robin with priority
@ -855,7 +1088,9 @@ This is the explanation for lines @samp{42-52}.
@section Writing plugins
@cindex plugins
TODO: write me
Writing plugins for SGPEMv2 goes outside the scope of this manual. For
some informations on how to extend it with a plugin of yours,
@xref{Top, , Writing your own plugins, sgpemv2dman, SGPEMv2 Developer Manual}.
@c % -------------------------------------------------
@c include license text