Add description of the preemption plugin

doc/html/Makefile.am

@@ -37,6 +37,7 @@ generated_html = \
 	plugins.html \
 	power_save.html \
 	preempt.html \
+	preemption_plugins.html \
 	proctrack_plugins.html \
 	priority_multifactor.html \
 	priority_plugins.html \

doc/html/Makefile.in

@@ -304,6 +304,7 @@ generated_html = \
 	plugins.html \
 	power_save.html \
 	preempt.html \
+	preemption_plugins.html \
 	proctrack_plugins.html \
 	priority_multifactor.html \
 	priority_plugins.html \

doc/html/documentation.shtml

@@ -66,6 +66,7 @@ Also see <a href="publications.html">Publications and Presentations</a>.
 <li><a href="checkpoint_plugins.html">Job Checkpoint Plugin Programmer Guide</a></li>
 <li><a href="jobcompplugins.html">Job Completion Logging Plugin Programmer Guide</a></li>
 <li><a href="mpiplugins.html">MPI Plugin Programmer Guide</a></li>
+<li><a href="preemption_plugins.html">Preemption Plugin Programmer Guide</a></li>
 <li><a href="priority_plugins.html">Priority Plugin Programmer Guide</a></li>
 <li><a href="proctrack_plugins.html">Process Tracking Plugin Programmer Guide</a></li>
 <li><a href="schedplugins.html">Scheduler Plugin Programmer Guide</a></li>
@@ -76,6 +77,6 @@ Also see <a href="publications.html">Publications and Presentations</a>.
 </li>
 </ul>
 
-<p style="text-align:center;">Last modified 24 March 2009</p>
+<p style="text-align:center;">Last modified 24 August 2009</p>
 
 <!--#include virtual="footer.txt"-->

doc/html/preemption_plugins.shtml

+<!--#include virtual="header.txt"-->
+
+<h1><a name="top">SLURM Preemption Plugin API</a></h1>
+
+<h2> Overview</h2>
+<p> This document describes SLURM preemption plugins and the API that defines
+them. It is intended as a resource to programmers wishing to write their own
+SLURM preemption plugins. This is version 100 of the API.</p>
+
+<p>SLURM preemption plugins are SLURM plugins that identify which jobs
+can be preempted by a pending job. They must conform to the SLURM Plugin 
+API with the following specifications:</p>
+
+<p><span class="commandline">const char
+plugin_type[]="<i>major/minor</i>"</span><br>
+The major type must be &quot;preempt.&quot; The minor type can be any
+recognizable abbreviation for the type of preemption.
+We recommend, for example:</p>
+
+<ul>
+<li><b>none</b>&#151;This plugin prevents any job preemption.</li>
+<li><b>partition_prio</b>&#151;This plugin permit pending jobs from one 
+partition to preempt jobs from a lower priority partition.</li>
+<li><b>qos</b>&#151;This plugin permits jobs to preempt others based 
+upon their Quality Of Service values as defined in the SLURM database.</li>
+</ul>
+
+<p>The <span class="commandline">plugin_name</span> and
+<span class="commandline">plugin_version</span> symbols required by the SLURM
+Plugin API require no specialization for job preemption support.
+Note carefully, however, the versioning discussion below.</p>
+
+<p>The programmer is urged to study
+<span class="commandline">src/plugins/preempt/partition_prio/preempt_partition_prio.c</span> 
+for an example implementation of a SLURM preemption plugin.</p>
+
+<p class="footer"><a href="#top">top</a></p>
+
+<h2>API Functions</h2>
+<p>The following functions must appear. Functions which are not implemented 
+should be stubbed.</p>
+
+<p class="commandline">struct job_record **find_preemptable_jobs(
+struct job_record *job_ptr)</p>
+<p style="margin-left:.2in"><b>Description</b>: Identifies the jobs 
+which can be preempted by a specific pending job.</p>
+<p style="margin-left:.2in"><b>Arguments</b>:<br>
+<span class="commandline">job_ptr</span> (input) a pointer to the 
+pending job which is attempting to be started</p>
+<p style="margin-left:.2in"><b>Returns</b>: An array of pointers to 
+jobs which may be preempted. 
+The array should be NULL terminated and will be released using 
+the <i>xfree</i> function when no longer required.
+This array should be sorted in order from most attractive to
+preempt to least attractive to preempt (e.g. lowest to highest priority).
+For example, even within a given partition or QOS one might want to 
+smaller jobs first.</p>
+
+<h2>Versioning</h2>
+<p> This document describes version 100 of the SLURM Preemption API. Future
+releases of SLURM may revise this API. A preemption plugin conveys its ability
+to implement a particular API version using the mechanism outlined for SLURM
+plugins.</p>
+
+<p class="footer"><a href="#top">top</a></p>
+
+<p style="text-align:center;">Last modified 24 August 2009</p>
+
+<!--#include virtual="footer.txt"-->