boinc/dcapi/doc/local.xml

<?xml version="1.0"?>
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" 
               "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
<sect1 id="local">
  <title>Standalone</title>

  <sect2 id="local_app">
  <title>Standalone application</title>

  <para>
  Standalone backend does not use any special execution environment to
  execute client jobs. Clients are spawned as local processes so the
  master and all workers are running as local processes on the same
  host. The execution host must be a UNIX wokstation because this is
  the only supported platform for this backend yet.
  </para>

  <sect3 id="local_name">
  <title>Name of the standalone backend</title>

  <para>The name of this backend is:</para>

  <para><emphasis>local</emphasis></para>

  <para>This name must be used to identify the backend when using the
  library to <link linkend="build-unix">build
  application</link>.</para>

  </sect3>

  <sect3 id="local_exec">
  <title>Execution of clients</title>

  <para> Call of <function><link
  linkend="DC-submitWU">DC_submitWU()</link></function> in master
  process spawns a new UNIX process using
  <function>fork</function>/<function>exec</function> mechanism and
  starts the executable of the client. Client changes its directory to
  its own working directory which is prepared by the master for
  it.</para>

  <para>Event handling procedures of the master process
  (<function><link
  linkend="DC-waitWUEvent">DC_waitWUEvent()</link></function>,
  <function><link
  linkend="DC-processMasterEvents">DC_processMasterEvents()</link></function>,
  etc.) check the operating system for the client's process and report
  it as finished when it disapears.</para>

  </sect3>

  <sect3 id="local_messaging">
  <title>Message passing</title>

  <para>It is possible to send messages between the master and a
  client (see <function><link
  linkend="DC-sendMessage">DC_sendMessage()</link></function> and
  <function><link
  linkend="DC-sendResult">DC_sendResult()</link></function>
  functions). Messages are passed as files. Message files are placed
  in "message boxes", which are directories created in client's
  working directory. Name of the message box directories can be
  specified by configuration options (see <link
  linkend="local_ClientMessageBox">ClientMessageBox</link>, and <link
  linkend="local_MasterMessageBox">MasterMessageBox</link>), so they
  will not interfere with client's own created files and
  directories.</para>

  <para>This backend maintains order of the messages so they will be
  received in the same order as they were sent.</para>

  </sect3>

  </sect2>

  <sect2 id="local_configuration">
  <title>Configuration options</title>

    <variablelist>

        <varlistentry>
	  <term>InstanceUUID</term>
	  <listitem>
	    <para>

	    REQUIRED. Identification of running instance of the
	    application. For Standalone backend it can be any string not
	    just an UUID.

	    </para>
	  </listitem>
        </varlistentry>

        <varlistentry>
	  <term>WorkingDirectory</term>
	  <listitem>
	    <para>
	    
	    REQUIRED. Name of working directory of the
	    application. All files that are generated by the
	    application or the DC-API library are placed under this
	    directory. Different applications can use the same working
	    directory because every instance has its own subdirectory
	    there.

	    </para>
	  </listitem>
	</varlistentry>

        <varlistentry id="local_ClientMessageBox">
	  <term>ClientMessageBox</term>
	  <listitem>
	    <para>

	    Name of the directory in workunit's working directory
	    where messages are placed which are sent by the client to
	    the master by <function><link
	    linkend="DC-sendMessage">DC_sendMessage()</link></function>. Default
	    value is <filename>_dcapi_client_messages</filename>.

	    </para>
	  </listitem>
	</varlistentry>

	<varlistentry id="local_MasterMessageBox">
	  <term>MasterMessageBox</term>
	  <listitem>
	    <para>

	    Name of the directory in workunit's working directory
	    where <function><link
	    linkend="DC-sendWUMessage">DC_sendWUMessage()</link></function>
	    places messages sent by the master to the client. Default
	    value is <filename>_dcapi_master_messages</filename>.

	    </para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term>SubresultBox</term>
	  <listitem>
	    <para>

	    Name of the directory in workunit's working directory
	    where <function><link
	    linkend="DC-sendResult">DC_sendResult()</link></function>
	    places subresults generated by the client. Default
	    value is <filename>_dcapi_client_subresults</filename>.

	    </para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term>Executable</term>
	  <listitem>
	    <para>

	    Name of the executable file of the client (workunit). By
	    default it is the <parameter>clientName</parameter>
	    parameter which was passed to <function><link
	    linkend="DC-createWU">DC_createWU()</link></function>.

	    </para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term>LeaveFiles</term>
	  <listitem>
	    <para>
	    
	    Specifies if files, directories generated in workunit's
	    working directory should be deleted or not after workunit
	    ends. Zero value means delete and non-zero value means not
	    to delete. Default value is 0.

	    </para>
	  </listitem>
	</varlistentry>

    </variablelist>

  </sect2>
</sect1>

<!-- End of local.xml -->