- 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:
parent
34825da69b
commit
461f29023e
|
@ -80,6 +80,9 @@ Free Documentation License''.
|
||||||
* Using the Mailing List:: How to compose your messages
|
* Using the Mailing List:: How to compose your messages
|
||||||
when contacting us on the ML
|
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
|
* License:: The full text of the license under which this
|
||||||
manual is given to you
|
manual is given to you
|
||||||
|
|
||||||
|
@ -298,7 +301,7 @@ documents or resources.
|
||||||
Other parts of the document are specific to the technical document
|
Other parts of the document are specific to the technical document
|
||||||
itself, and therefore should be managed by the editor.
|
itself, and therefore should be managed by the editor.
|
||||||
Mostly, the general structure for the more common documents can be found at
|
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 Italian).
|
||||||
|
|
||||||
In the @samp{docs/misc/} directory of the Subversion repository,
|
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
|
@cindex documenting C++ code
|
||||||
|
|
||||||
Please refer to @emph{Doxygen} manual
|
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
|
in order to learn how to use this automatic tool for extracting
|
||||||
documentation from code.
|
documentation from code.
|
||||||
|
|
||||||
|
@ -386,7 +389,7 @@ to learn more of it.
|
||||||
However, if we want to generate good documentation straight
|
However, if we want to generate good documentation straight
|
||||||
from code, with the help of Doxygen, we should use the @samp{#}
|
from code, with the help of Doxygen, we should use the @samp{#}
|
||||||
documenting style. Please look at the end of
|
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.
|
an example.
|
||||||
|
|
||||||
@c % ----- new subsection
|
@c % ----- new subsection
|
||||||
|
@ -1102,7 +1105,7 @@ Never use global static variables of non-POD (Plain Old Data)
|
||||||
type.
|
type.
|
||||||
The reason why not doing this is fundamental, and it is well
|
The reason why not doing this is fundamental, and it is well
|
||||||
described, along with a possible alternative here:
|
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
|
@end enumerate
|
||||||
|
|
||||||
|
@ -1370,7 +1373,7 @@ practice, locking seems to inhibit productivity more than anything else.
|
||||||
|
|
||||||
@c % --------------------------------------------------
|
@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
|
@chapter Using the Mailing List
|
||||||
@cindex mailing list
|
@cindex mailing list
|
||||||
|
|
||||||
|
@ -1550,7 +1553,15 @@ Have fun, and ...
|
||||||
@c % --------------------------------------------------
|
@c % --------------------------------------------------
|
||||||
|
|
||||||
@c include license text
|
@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
|
@include fdl.texi
|
||||||
|
|
||||||
@c % --------------------------------------------------
|
@c % --------------------------------------------------
|
||||||
|
|
|
@ -92,7 +92,8 @@ Free Documentation License''.
|
||||||
@item 2006, September 8th @r{-- Matteo Settenvini}
|
@item 2006, September 8th @r{-- Matteo Settenvini}
|
||||||
Update chapters about building and installation. Rewrite some of the
|
Update chapters about building and installation. Rewrite some of the
|
||||||
chapter about extending SGPEMv2 with custom CPU policies, and add a
|
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}
|
@item 2006, September 7th @r{--- Luca Vezzaro}
|
||||||
First attempt at expanding the manual structure with the
|
First attempt at expanding the manual structure with the
|
||||||
stuff we'll need in the forthcoming beta testing
|
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?
|
@subsection What is a policy in SGPEM?
|
||||||
@cindex policies basics
|
@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
|
@node What kind of policies are there?, Built-in policies, What is a policy in SGPEM?, Policies
|
||||||
@subsection What kind of policies are there?
|
@subsection What kind of policies are there?
|
||||||
@cindex policies kinds
|
@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
|
@subsection Built-in policies
|
||||||
@cindex 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 % -------------------------------------------------
|
@c % -------------------------------------------------
|
||||||
@node The Scheduler, (none), Policies, Basics
|
@node The Scheduler, (none), Policies, Basics
|
||||||
@section The Scheduler
|
@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}
|
@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 % -------------------------------------------------
|
@c % -------------------------------------------------
|
||||||
@node The Schedulables/Requests tree, The Resources list, Overall view of the main window, From the GUI
|
@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
|
a running thread in the queue. See the following example for some tips
|
||||||
about how to manage this case.
|
about how to manage this case.
|
||||||
|
|
||||||
Pay attention to the fact that we used the @code{<=} relation at line @samp{12}, and
|
Pay attention to the fact that we used the @code{<=} relation at line
|
||||||
not a simple @code{<}. This is because @code{queue.sort()} uses a
|
@samp{12}, and not a simple @code{<}. This is because
|
||||||
in-place implementation of quicksort, which is stable only when
|
@code{queue.sort()} uses a in-place implementation of quicksort.
|
||||||
employed with a minor-or-equal relation. Otherwise the queue would be
|
@xref{ReadyQueue.sort_queue()}. If your policy behaves strangely,
|
||||||
sorted, but two adjacent threads that have the same value for a given
|
this may be the cause.
|
||||||
priority would be swapped. If your policy behaves strangely, this may
|
|
||||||
be the cause.
|
|
||||||
|
|
||||||
@end table
|
@end table
|
||||||
|
|
||||||
@c % --------- new subsection
|
@c % --------- new subsection
|
||||||
@subsection Exposed interface: what you can use
|
@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}
|
@anchor{Configuring parameters}
|
||||||
@subsubsection Configuring parameters
|
@subsubsection Configuring parameters
|
||||||
|
|
||||||
TODO: list and describe all methods exposed from PolicyParameters.
|
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
|
@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
|
@subsubsection Properties of schedulable entities
|
||||||
|
|
||||||
TODO: list and describe all methods exposed from Schedulable,
|
All schedulables, both threads and processes, implement the following methods:
|
||||||
Thread and Process
|
|
||||||
|
|
||||||
|
@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
|
@c % --------- new subsection
|
||||||
@subsection A more complete example: Round Robin with priority
|
@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
|
@section Writing plugins
|
||||||
@cindex 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 % -------------------------------------------------
|
||||||
@c include license text
|
@c include license text
|
||||||
|
|
Loading…
Reference in New Issue