- 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
parent
34825da69b
commit
461f29023e
|
|
@ -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 % --------------------------------------------------
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Reference in New Issue