<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [
<!ENTITY general-cmdline-options-sect SYSTEM "general-cmdline-options-sect.xml">
<!ENTITY author-sect                  SYSTEM "author-sect.xml">
<!ENTITY bugs-sect                    SYSTEM "bugs-sect.xml">
<!ENTITY caveats-sect                 SYSTEM "caveats-sect.xml">
<!ENTITY exit-status-sect             SYSTEM "exit-status-sect.xml">
]>
<refentry status="draft" id="serelhistory">

<refentryinfo>
<!--  <date>2002-05-23</date> -->
<author>
<firstname>Leni</firstname>
<surname>Mayo</surname>
</author>
</refentryinfo>

<refmeta>
<refentrytitle><application>serelhistory</application></refentrytitle>
<manvolnum>8</manvolnum>
<refmiscinfo>serelhistory 0.3.2</refmiscinfo>
</refmeta>

<refnamediv>
<refname><application>serelhistory</application></refname>

<refpurpose>Manage and use historical service relationships</refpurpose>
</refnamediv>

<refsynopsisdiv>
<cmdsynopsis>
<command>serelhistory</command>
<arg><option>general options</option></arg>
<!-- <arg choice="req"><option>options</option></arg> -->
<group choice="opt">
<arg choice="plain">--populate</arg>
<arg choice="plain">--query</arg>
<arg choice="plain">--apply-started</arg>
<arg choice="plain">--apply</arg>
</group>
</cmdsynopsis>
</refsynopsisdiv>

<refsect1> <title>DESCRIPTION</title>

<para>
<command>serelhistory</command> improves the performance of a parallel boot by allowing dependency information to persist across boot invocations.
</para>

<para>
One of the following options must be selected: "populate", "query", "apply", "apply-started".
</para>

<para>
Populate the history:
<itemizedlist mark="none">
<listitem>
<cmdsynopsis>
<command>serelhistory</command>
<arg><option>general options</option></arg>
<arg choice="plain"><option>--populate</option></arg>
</cmdsynopsis>
</listitem>
</itemizedlist>
</para>

<para>
Query the history:
<itemizedlist mark="none">
<listitem>
<cmdsynopsis>
<command>serelhistory</command>
<arg><option>general options</option></arg>
<arg choice="plain"><option>--query</option> <replaceable class="parameter">args</replaceable></arg>
</cmdsynopsis>
</listitem>
</itemizedlist>
</para>

<para>
Register services as having already started:
<itemizedlist mark="none">
<listitem>
<cmdsynopsis>
<command>serelhistory</command>
<arg><option>general options</option></arg>
<arg choice="plain"><option>--apply-started</option></arg>
</cmdsynopsis>
</listitem>
</itemizedlist>
</para>

<para>
Register the service (and dependencies) associated with a pathname:
<itemizedlist mark="none">
<listitem>
<cmdsynopsis>
<command>serelhistory</command>
<arg><option>general options</option></arg>
<arg choice="plain"><option>--apply</option> <replaceable class="parameter">path</replaceable></arg>
</cmdsynopsis>
</listitem>
</itemizedlist>
</para>

<para>
<command>serelhistory</command> supports the four basic steps involved with running boot scripts in parallel:
<orderedlist numeration="arabic" spacing="compact">
<listitem>
<para>
Selection of service definitions from among the available sources.  Service defintions can be found in .rdf files, and in specially-formatted comments inside boot scripts.
</para>
</listitem>

<listitem>
<para>
Construction of a dependency graph, informed by:
<itemizedlist>
<listitem><para>the service definitions found in step 1 above</para></listitem>
<listitem><para>the collection of services being started (or stopped) as a unit</para></listitem>
<listitem><para>the collection of services that were last started (or stopped) as a unit</para></listitem>
</itemizedlist>
</para>
</listitem>

<listitem>
<para>
Testing the dependency graph for integrity
</para>
</listitem>

<listitem>
<para>
Applying the dependencies represented by the graph
</para>
</listitem>

</orderedlist>
</para>

<para>
Data from steps 1-3 are persistent, so that a subequent boot using the same services and service-definitions avoids the processing associated with these steps.
</para>

</refsect1>

&general-cmdline-options-sect;

<refsect1>
<title>POPULATING THE HISTORY</title>
<para>
This option takes the form:
<cmdsynopsis>
<command>serelhistory</command>
<arg><option>general options</option></arg>
<arg choice="plain"><option>--populate</option></arg>
</cmdsynopsis>
The set of services that are being started as a unit are read from standard input, which takes the form:
<cmdsynopsis>

<arg choice="opt"> --started <arg rep="repeat" choice="req">
<group choice="opt"><replaceable class="parameter">service</replaceable></group>
</arg>
</arg>
</cmdsynopsis>

followed by:

<cmdsynopsis>
<arg choice="plain"> --pairs <arg rep="repeat" choice="req">
<arg choice="opt">
<replaceable class="parameter">service</replaceable> 
<replaceable class="parameter">path</replaceable>
</arg>
</arg>
</arg>
</cmdsynopsis>
</para>

</refsect1>

<refsect1>
<title>QUERYING THE HISTORY</title>
<para>
This option takes the form:
<cmdsynopsis>
<command>serelhistory</command>
<arg><option>general options</option></arg>
<arg choice="plain"><option>--query</option> <replaceable class="parameter">args</replaceable></arg>
</cmdsynopsis>
where <replaceable>args</replaceable> is one of:

<variablelist>

<varlistentry>
<term>verify</term>
<listitem>
<para>
This tests that a directed, acyclic graph can built from the services given to --populate.  None of the following can be true for the test to succeed:
<itemizedlist>
<listitem><simpara>
service A depends on service B, and no dependency information is available for service B
</simpara></listitem>
<listitem><simpara>
the graph is cyclic.  That is, service A depends on service B, and (even indirectly) service B depends upon service A
</simpara></listitem>
</itemizedlist>
</para>
<para>
The single word <quote>success</quote> is sent to standard output if the test succeeds,
otherwise an informational message.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>prior-history</term>
<listitem>
<para>
This tests whether the last call to <command>serelhistory --populate</command>
used history information from a prior boot.  The single word
<quote>success</quote> is sent to standard output if history information from
a prior boot was used, otherwise an informational message.
</para>
</listitem>
</varlistentry>

</variablelist>
</para>
</refsect1>

<refsect1>
<title>SERVICES THAT HAVE ALREADY STARTED</title>
<para>
This option takes the form:
<cmdsynopsis>
<command>serelhistory</command>
<arg><option>general options</option></arg>
<arg choice="plain"><option>--apply-started</option></arg>
</cmdsynopsis>
</para>
<para>
Some services may have already started outside the serel framework - 
the names of these services are passed to the daemon via 
--populate.
</para>
<para>
This option instructs the daemon to register the already-started services.  This option is equivalent
to running <quote><command>serelc</command> --provide</quote> for each of the already-started services.
</para>
</refsect1>

<refsect1>
<title>STARTING SERVICES</title>
<para>
This option takes the form:
<cmdsynopsis>
<command>serelhistory</command>
<arg><option>general options</option></arg>
<arg choice="plain"><option>--apply</option></arg>
</cmdsynopsis>
</para>
<para>
Populating the history establishes relationships between pathnames and services.
</para>
<para>
This command instructs the daemon to apply the serelc --provide, --need, and --unprovide
statements corresponding to the given pathname.
</para>
<para>
The command is equivalent to, but more efficient than the following steps:
<itemizedlist>
<listitem>
<simpara>
querying the daemon for the service provided by the given path
</simpara>
</listitem>
<listitem>
<simpara>
executing "serelc --provide" for the provided service
</simpara>
</listitem>
<listitem>
<simpara>
executing "serelc --need" for each service required by the provided service
</simpara>
</listitem>
</itemizedlist>
</para>
</refsect1>

&exit-status-sect;

&caveats-sect;

&bugs-sect;

<refsect1>
<title>SEE ALSO</title>
<para>
<command>serelc (8)</command>, <command>sereld (8)</command>
</para>
</refsect1>

&author-sect;

</refentry>

