add explanation of overlapping reservations

doc/html/reservations.shtml

@@ -2,11 +2,11 @@
 
 <h1>Resource Reservation Gude</h1>
 
-<p>SLURM verstion 2.0 has the ability to reserve resources for jobs
+<p>SLURM version 2.0 has the ability to reserve resources for jobs
 being executed by select users and/or select bank accounts.
 A resource reservation identifies the nodes of a resource reservation 
 and a time period during which the reservation is available.
-Note that resource reservations are not compatable with SLURM's
+Note that resource reservations are not compatible with SLURM's
 gang scheduler plugin since the termination time of running jobs
 is not possible to accurately predict.</p>
 
@@ -65,7 +65,7 @@ Reservation created: root_4
 $ scontrol show reservation
 ReservationName=root_4 StartTime=2009-04-06T16:00:00 
    EndTime=2009-04-06T18:00:00 Duration=120
-   Nodes=ALL NodeCnt=20
+   Nodes= NodeCnt=0
    Features=(null) PartitionName=(null)
    Flags=MAINT,SPEC_NODES,IGNORE_JOBS Licenses=lustre*1000
    Users=root Accounts=(null)
@@ -92,7 +92,7 @@ ReservationName=root_5 StartTime=2009-02-04T16:22:57
 
 <p>Our final example is to reserve ten nodes in the default 
 SLURM partition starting at noon and with a duration of 60 
-minutes occuring daily. The reservation will be available
+minutes occurring daily. The reservation will be available
 only to users alan and brenda.</p>
 <pre>
 $ scontrol create reservation user=alan,brenda \
@@ -115,18 +115,6 @@ reservation. Note that the reservation creation request can also
 identify the partition from which to select the nodes or _one_
 feature that every selected node must contain.</p>
 
-<p>Reservations must not overlap, with the exception of 
-maintenance mode as described below. They must either include 
-different nodes or operate at different times. If specific nodes
-are not specified when a reservation is created, SLURM will 
-automatically select nodes to avoid overlap and insure that
-the selected nodes are available when the reservation begins.
-For ease of system maintenance, you can create a reservation
-with the "maint" flag that overlaps existing reservations.
-This permits an administrator to easily create a maintenance 
-reservation for an entire cluster without needing to remove 
-or reschedule pre-existing reservations.</p>
-
 <h2>Reservation Use</h2>
 
 <p>The reservation create response includes the reservation's name.
@@ -134,7 +122,7 @@ This name is automatically generated by SLURM based upon the first
 user or account name and a numeric suffix. In order to use the 
 reservation, the job submit request must explicitly specify that
 reservation name. The job must be contained completely within the
-named reservation. The job will be cancelled after the reservation 
+named reservation. The job will be canceled after the reservation 
 reaches its EndTime. If letting the job continue execution after
 the reservation EndTime, a configuration option <i>ResvOverRun</i>
 can be set to control how long the job can continue execution.</p>
@@ -158,7 +146,7 @@ ReservationName=root_3 StartTime=2009-02-06T16:00:00
    EndTime=2009-02-06T18:30:00 Duration=150
    Nodes=ALL NodeCnt=20 Features=(null) 
    PartitionName=(null) Flags=MAINT,SPEC_NODES Licenses=(null)
-   Users=jette Accounts=(null)
+   Users=admin Accounts=(null)
 </pre>
 
 <h2>Reservation Deletion</h2>
@@ -171,6 +159,59 @@ jobs running in it.</p>
 $ scontrol delete ReservationName=alan_6
 </pre>
 
+<h2>Overlapping Reservations</h2>
+
+<p>By default, reservations must not overlap. They must either include 
+different nodes or operate at different times. If specific nodes
+are not specified when a reservation is created, SLURM will 
+automatically select nodes to avoid overlap and insure that
+the selected nodes are available when the reservation begins.</p>
+
+<p>There is very limited support for overlapping reservations
+with two specific modes of operation available.
+For ease of system maintenance, you can create a reservation
+with the "maint" flag that overlaps existing reservations.
+This permits an administrator to easily create a maintenance 
+reservation for an entire cluster without needing to remove 
+or reschedule pre-existing reservations. Users requesting access 
+to one of these pre-existing reservations will be prevented from
+using resources that are also in this maintenance reservation. 
+For example, users alan and brenda might have a reservation for
+some nodes daily from noon until 1PM. If there is a maintenance
+reservation for all nodes starting at 12:30PM, the only jobs they 
+may start in their reservation would have to be completed by 12:30PM,
+when the maintenance reservation begins.</p>
+
+<p>The second exception operates in the same manner as a maintenance 
+reservation except that is it not logged in the accounting system as nodes 
+reserved for maintenance. 
+It requires the use of the "overlap" flag when creating the second 
+reservation.
+This might be used to insure availability of resources for a specific
+user within a group having a reservation. 
+Using the previous example of alan and brenda having a 10 node reservation 
+for 60 minutes, we might want to reserve 4 nodes of that for for brenda
+during the first 30 minutes of the time period. 
+In this case, the creation of one overlapping reservation (for a total of
+two reservations) may be simpler than creating three separate reservations, 
+partly since the use of any reservation requires the job specification 
+of the reservation name.
+<ol>
+<li>A six node reservation for both alan and brenda that lasts the full 
+60 minutes</li>
+<li>A four node reservation for brenda for the first 30 minutes</li>
+<li>A four node reservation for both alan and brenda that lasts for the 
+final 30 minutes</li>
+</ol></p>
+
+<p>If the "maint" or "overlap" flag is used when creating reservations, 
+one could create a reservation within a reservation within a third 
+reservation. 
+Note a reservation having a "maint" or "overlap" flag will not have 
+resources removed from it by a subsequent reservation also having a 
+"maint" or "overlap" flag, so nesting of reservations only works to a 
+depth of two.</p>
+
 <h2>Reservation Accounting</h2>
 
 <p>Jobs executed within a reservation are accounted for using the appropriate
@@ -187,10 +228,15 @@ to have used half of the reserved resources).</p>
 <li>The automatic selection of nodes for a reservation create request may be
 sub-optimal in terms of locality (for optimized application 
 communication).</li> 
+<li>Reservations made within a partition having gang scheduling assumes
+the highest level rather than the actual level of time-slicing when 
+considering the initiation of jobs.
+This will prevent the initiation of some jobs which would complete execution 
+before a reservation given fewer jobs to time-slice with.</li>
 </ol>
 
 
-<p style="text-align: center;">Last modified 1 July 2009</p>
+<p style="text-align: center;">Last modified 25 August 2009</p>
 
 <!--#include virtual="footer.txt"-->