- Update manuals with:

* exposed interface
  * scheduling policies description


git-svn-id: svn://svn.gna.org/svn/sgpemv2/trunk@1071 3ecf2c5c-341e-0410-92b4-d18e462d057c

doc/sgpem2dman.texi

@@ -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 % --------------------------------------------------

doc/sgpem2uman.texi

@@ -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
+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
 
 @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, 
+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
 @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