- User manual, Basics and Prerences Dialog

- Added a new environment to test the difference
  between atomic and non atomic requests


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

doc/sgpem2uman.texi

@@ -404,13 +404,54 @@ didn't have it previously installed, you may need to re-run @command{configure}.
 
 @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.
+* Policies:: Everything you'll ever wanted to know about policies
+             in SGPEM!
 
 @end menu
 
+@c % -------------------------------------------------
+@node The Scheduler, (none), Policies, Basics
+@section The Scheduler
+@cindex scheduler basics
+
+From the scheduler's point of view, the simulated environment is populated
+by processes and resources. Processes are spawned at differnt instants and 
+compete for the CPU and other resources until their termination.
+
+Processes have an arrival time, i. e. an instant at wich they are spawned,
+and a priority.
+
+Our application simulates the scheduling of threads, not the scheduling of 
+processes. Anyway, it is possible to simulate processes scheduling simply placing 
+one single thread within each process, and hiding thread details on the GUI.
+
+In SGPEM, a process is quite just a container of threads. Threads have a
+required cpu time, a priority within the process, and an arrival time delta.
+The arrival time delta of a thread is relative to the execution time of the parent
+process, and not to the arrival time of the parent process.
+
+The scheduler's task is to assign the cpu and the other resources to the 
+processes. Both resources and CPU are mutually exclusive, meaning that no two
+processes may use them at the same time.
+
+A thread may raise requests at any time of its execution: a request has a raising
+time delta, which is relative to the execution time of the owner thread, and not 
+to the arrival time of the owner thread.
+
+A request specifies a set of resources and the time they are requested for.
+The specified set of resources will be acquired atomically, meaning that either all
+of the requested resources is given to the thread, or none of them is.
+
+A thread may raise any number of requests at any instant. Requiring four resources
+may be done either atomically, specifying one request with four separate subrequests,
+or non-atomically, specifying four requests with one subrequest each. A subrequest
+is the specification of which resource and for how much time.
+
+Resources have multiplicity, or places. A resource with two places acts like two 
+indistinguishable resources.
+
 @c % -------------------------------------------------
 @node Policies, The Scheduler, Basics, Basics
 @section Policies
@@ -420,9 +461,8 @@ didn't have it previously installed, you may need to re-run @command{configure}.
 
 * 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
+* What kind of policies are there?:: In SGPEM there are many species of policies. Here
-                                     kinds of policies. This subsection explains 
+                                     you will explore our zoo.
-				     these differences.
 * Built-in policies:: Here you will find a detailed descriptions of the policies 
                       shipped with the standard distribution of SGPEM.
 
@@ -432,14 +472,101 @@ 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
+A policy is a rule used by the scheduler to decide which thread should run next.
-that if you want to schedule processes just put into them one single
+Our scheduler needs two different policies to perform this choice: one is called a 
-thread and choose to hide threads from the GUI.
+cpu (scheduling) policy and the other is called a resource (scheduling) policy.
+
+@subsubsection CPU Scheduling Policies
+
+The first, from now on called simply "policy", is the rule telling which of the
+ready (or running) threads is the best candidate to get the cpu. For example, the 
+FCFS policy is a rule which tells that, among the ready threads, the one which 
+asked the CPU first is the best candidate. The Lottery policy is a rule which tells 
+that, among the ready threads, one chosen at random is the best candidate.
+
+Being the best candidate means to get the CPU and try to run: anyway, getting the cpu 
+does not mean to be able to run: a thread may need a resource to complete its work,
+and mutually exclusive resources may be locked by other threads. In this event 
+a thread is said to raise a request for some resources, and to get blocked by those
+requests.
+
+@subsubsection Resource Scheduling Policies
+
+The second policy is the rule telling, for each resource, which of the raised requests
+are the allowed to be satisfied, according to the places offered by the resource.
+For example, the FIFO resource policy is a rule which tells that, among the raised requests, the ones which 
+came first are allowed to be allocated. An other example, the Priority policy 
+is a rule which, roughly speaking, tells that, among the raised requests, the ones having higher priority
+are allowed to be allocated.
+
+SGPEM provides some resource policies, but it does not allow the user to create its own.
+Like cpu scheduling policies, resource policies are parametric, altough at the moment none 
+of the included is.
+Resource policies are largely dependant on the mehcanism of the scheduler, and since is
+very complex to understand the mechanism of scheduler, it would be wasteful to provide
+an extension mechanism for resource policies: the user willing to implement a new resource
+scheduling policy would better understand and adapt the SGPEM source code.
+
+@subsubsection Policy Parameters
+
+A policy in SGPEM is in general a parametric rule: this means that the user should set some parameters
+to actually use the policy. Parameters are either integer, float or string values, which
+further specify the behavior of the policy: for example, the round-robin policy needs
+the user to choose the length of a time slice. Parametric policies always provide default
+values for their parameters, thus the user is not forced to set them manually. (see gui_set_policy)
+
 
 @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
 
+SGPEM defines four classes of policies, and the scheduler uses different kinds of policies
+in different ways. The four kinds are: Simple, Time-sharing, Preemptive, Preemptive and Time-sharing.
+
+@subsubsection Simple policies
+Simple policies may change the running thread only when the running one has blocked or has terminated.
+A simple policy is allowed to change the running thread at any instant during the simulation, replacing
+it with the best candidate among the set of all the ready threads.
+
+@subsubsection Time-sharing policies
+Within SGPEM, a policy is said to be time-shared when the policy may change the 
+running thread after it has been running for a full time-slice (or time quantum).
+The size of the time-slice is supposed to be fixed, and varying the size of the 
+time-slice during the simulaiton is possible, altought not very useful.
+A time-sharing policy is allowed to change the running thread only when it has exhausted
+its quantum, or it has blocked, or it has terminated, replacing it with the best candidate
+among the set of all the ready or running(*) threads.
+
+* At the moment any running thread which used up its quantum is set to ready, therefore there is no 
+running thread to choose when a time-sharing policy is used.
+
+@subsubsection Preemptive policies
+Within SGPEM, a policy is said to be preemptive (or priority-preemptive, too) when
+the policy may change the running thread for priority reasons. A preemptive policy
+is allowed to change the running thread at any instant during the simulation, replacing
+it with the best candidate among the set of all the ready or running threads.
+Note that this meaning of the adjective "preemptive" may not match the one
+found in your favourite operating systems reference book.
+
+Actually, our application does not check if the preemption is done for priority 
+reasons, so one could, in principle, implement time-shared policies without specifying
+a fixed size for the time slice, i. e. without declaring the policy as time-shared.
+Time-sharing may be implemented using an internal counter, relying on the fact that
+a preemptive policy is called exactly at every instant.
+
+@subsubsection Preemptive and Time-sharing policies
+These policies are used by scheduler roughly in the same way as preemptive policies are.
+
+Note that altough this distinction is enough to understand most of the common policies,
+SGPEM is not that simple (wasn't it simple?).
+The actual implementation does not partition the space of policies in four classes: a real
+SGPEM policy may in fact dynamically "change its class", thus not fit in any of the previously listed.
+
+For using full-blown policies, advanced users should look directly
+at the mechanism itself.
+
+
+
 @node Built-in policies, (none), What kind of policies are there?, Policies
 @subsection Built-in policies
 @cindex built-in policies
@@ -503,16 +630,31 @@ end of the time slice.
 
 @subsubsection Resource scheduling policies
 
-TODO: write me!
-
 @table @asis
 
+@item First in first out
+
+A resource policy which satisfies earlier requests before older ones.
+
+This policy has no options to configure.
+
+@item Last in first out
+
+A resource policy which allows a request to be immediately allocated if there is enough space.
+
+This policy has no options to configure.
+
+@item Higher Priority First
+
+A resource policy which satisfies higher priority requests before lower priority ones.
+
+Note that a thread with priority 0 has an higher prioriy than a thread with priority 5.
+
+This policy has no options to configure.
+
 @end table
 
-@c % -------------------------------------------------
+
-@node The Scheduler, (none), Policies, Basics
-@section The Scheduler
-@cindex scheduler basics
 
 
 @c % --------------------------------------------------
@@ -668,9 +810,22 @@ request!
 @cindex preferences
 
 @strong{TODO:} Spiegare:
-a) quale ordine viene applicato per il caricamento dei plugin   
+
-b) dove vengono salvate le preferenze   
+The preferences window allow the user to set the simulation speed.
-c) cos'è l'intervallo
+The simulation speed is minimum waiting time between a step and an other; since computing
+the next step of the simulation may require the allocation of many resources, the specified
+speed may only be set as a minimum.
+
+The preferences window also allow the user to add and remove the directories where 
+policies and the plugins are found and loaded from.
+
+Changes regarding policies and plugins will be applied at the next run of SGPEM.
+
+Preferences are saved and loaded from the sgpem.cfg file located in the 
+installation directory.
+Preferences are loaded when the application is started, and saved when the "Close" 
+button of the dialogis pressed.
+
 
 @c % -------------------------------------------------
 @node Controlling the simulation, (none), The Preferences dialog, From the GUI

src/testsuite/scheduling-wizards/environments/Ducks_rr_2.xgp

@@ -0,0 +1,55 @@
+<?xml version="1.0"?>
+<!DOCTYPE sgpem SYSTEM "sgpem.dtd">
+<sgpem>
+  <resources>
+    <resource name="$ 1" id="reskey0" arrival-time="0" how-many="1" pre-emptible="false"/>
+    <resource name="$ 5" id="reskey1" arrival-time="0" how-many="1" pre-emptible="false"/>
+    <resource name="$ 10" id="reskey2" arrival-time="0" how-many="1" pre-emptible="false"/>
+    <resource name="$ 50" id="reskey3" arrival-time="0" how-many="1" pre-emptible="false"/>
+  </resources>
+  <schedulables>
+    <process name="Donald Duck" priority="0" arrival-time="0">
+      <threads>
+        <thread name="go for a walk" priority="3" arrival-delta="0" lasts-for="6">
+          <requests/>
+        </thread>
+        <thread name="collect money" priority="0" arrival-delta="4" lasts-for="3">
+          <requests>
+            <request arrival-time="0">
+              <subrequest resource="2" lasts-for="3"/>
+            </request>
+            <request arrival-time="1">
+              <subrequest resource="1" lasts-for="2"/>
+            </request>
+            <request arrival-time="2">
+              <subrequest resource="3" lasts-for="1"/>
+            </request>
+          </requests>
+        </thread>
+      </threads>
+    </process>
+    <process name="Uncle Scrooge" priority="0" arrival-time="1">
+      <threads>
+        <thread name="go for a walk" priority="3" arrival-delta="0" lasts-for="6">
+          <requests/>
+        </thread>
+        <thread name="collect money" priority="0" arrival-delta="3" lasts-for="1">
+          <requests>
+            <request arrival-time="0">
+              <subrequest resource="0" lasts-for="1"/>
+            </request>
+            <request arrival-time="0">
+              <subrequest resource="1" lasts-for="1"/>
+            </request>
+            <request arrival-time="0">
+              <subrequest resource="2" lasts-for="1"/>
+            </request>
+            <request arrival-time="0">
+              <subrequest resource="3" lasts-for="1"/>
+            </request>
+          </requests>
+        </thread>
+      </threads>
+    </process>
+  </schedulables>
+</sgpem>