mirror of https://github.com/BOINC/boinc.git
Documentation updates
git-svn-id: svn+ssh://cvs.lpds.sztaki.hu/var/lib/svn/szdg/dcapi/trunk@823 a7169a2c-3604-0410-bc95-c702d8d87f7a
This commit is contained in:
gombasg
Adam Visegradi
parent
f767af2a40
commit
877e3c3c43
|
|
@ -55,7 +55,7 @@ HTML_IMAGES=
|
|||
|
||||
# Extra SGML files that are included by $(DOC_MAIN_SGML_FILE).
|
||||
# e.g. content_files=running.sgml building.sgml changes-2.0.sgml
|
||||
content_files=
|
||||
content_files=intro.xml config.xml
|
||||
|
||||
# SGML files where gtk-doc abbrevations (#GtkWidget) are expanded
|
||||
# These files must be listed here *and* in content_files
|
||||
|
|
|
|||
|
|
@ -0,0 +1,177 @@
|
|||
<?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="configuration">
|
||||
<title>Configuration</title>
|
||||
|
||||
<para>
|
||||
The DC-API library uses a configuration file to control its operations. The
|
||||
location of the config file must be specified by the master application when
|
||||
it calls the <link linkend="DC_initMaster">DC_initMaster()</link> function.
|
||||
<note>
|
||||
Individual work units may also use a config file that has a slightly
|
||||
different format than the master's config file. Work unit config files
|
||||
however are usually generated by the DC-API library on the master side so
|
||||
applications should not be concerned about it.
|
||||
</note>
|
||||
</para>
|
||||
|
||||
<sect2>
|
||||
<title>Configuration file format</title>
|
||||
|
||||
<para>
|
||||
The DC-API configuration file contains key-value pairs organized into
|
||||
groups. The full syntax description can be found in the
|
||||
<ulink
|
||||
url="http://freedesktop.org/Standards/desktop-entry-spec">Desktop
|
||||
Entry Specification</ulink>, but we
|
||||
also give a brief explanation below.
|
||||
</para>
|
||||
<para>
|
||||
Lines starting with <literal>#</literal> are considered comments
|
||||
and are ignored. Groups are started by a line containing the group's name
|
||||
between brackets (<literal>[</literal> and <literal>]</literal>). Groups
|
||||
are terminated by the start of an other group or by the end of the file.
|
||||
</para>
|
||||
<para>
|
||||
A group may contain a list of <literal>key = value</literal> assignments,
|
||||
each in a separate line. White space arount the <literal>=</literal>
|
||||
character is ignored. Note that the DC-API do not use the localized string
|
||||
feature of the Desktop Entry Specification.
|
||||
</para>
|
||||
</sect2>
|
||||
|
||||
<sect2>
|
||||
<title>Generic configuration items</title>
|
||||
|
||||
<para>
|
||||
The DC-API configuration file should contain a group called
|
||||
<literal>Master</literal> that defines global configuration options.
|
||||
There may be also groups called <literal>Client-CLIENTNAME</literal> where
|
||||
<literal>CLIENTNAME</literal> is the logical name of a client application
|
||||
the master wishes to start (the same string that is passed to the
|
||||
<link linkend="DC_createWU">DC_createWU()</link> function).
|
||||
</para>
|
||||
|
||||
<sect3>
|
||||
<title>Configuration values for the master application</title>
|
||||
|
||||
<para>
|
||||
The following entries can be specified in the <literal>Master</literal>
|
||||
group. Grid backends may require and/or allow further items; refer to the
|
||||
backend-specific documentation.
|
||||
</para>
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term>WorkingDirectory</term>
|
||||
<listitem>
|
||||
<para>
|
||||
REQUIRED. The working directory of the master application. The value
|
||||
must be an absolute path. The DC-API sets the master's current
|
||||
directory to the value specified here when the <link
|
||||
linkend="DC_initMaster">DC_initMaster()</link> function is called.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>InstanceUUID</term>
|
||||
<listitem>
|
||||
<para>
|
||||
REQUIRED. The value must be a Universally Unique Identifier. The
|
||||
value must be unique for every master application running on the
|
||||
same grid backend. If two master applications are started with the
|
||||
same <literal>InstanceUUID</literal> value, their behaviour is
|
||||
undefined.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>LogLevel</term>
|
||||
<listitem>
|
||||
<para>
|
||||
OPTIONAL. Specifies the verbosity of log messages generated by the
|
||||
DC-API or by the master application if it uses the <link
|
||||
linkend="DC_log">DC_log()</link> or <link
|
||||
linkend="DC_vlog">DC_vlog()</link> functions. The allowed values
|
||||
in the order of increasing priority are <literal>Debug</literal>,
|
||||
<literal>Info</literal>, <literal>Notice</literal>,
|
||||
<literal>Warning</literal>, <literal>Error</literal> and
|
||||
<literal>Critical</literal>, the default being
|
||||
<literal>Notice</literal>.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>LogFile</term>
|
||||
<listitem>
|
||||
<para>
|
||||
OPTIONAL. Specifies the name of the file where log messages should
|
||||
be written to. If not specified, log messages are sent to the
|
||||
application's standard output.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
</sect3>
|
||||
<sect3>
|
||||
<title>Configuration values individual work units</title>
|
||||
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term>LogLevel</term>
|
||||
<listitem>
|
||||
<para>
|
||||
OPTIONAL. Specifies the verbosity of log messages generated by the
|
||||
DC-API or by the client application if it uses the <link
|
||||
linkend="DC_log">DC_log()</link> or <link
|
||||
linkend="DC_vlog">DC_vlog()</link> functions. The allowed values
|
||||
in the order of increasing priority are <literal>Debug</literal>,
|
||||
<literal>Info</literal>, <literal>Notice</literal>,
|
||||
<literal>Warning</literal>, <literal>Error</literal> and
|
||||
<literal>Critical</literal>, the default being
|
||||
<literal>Notice</literal>.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>LogFile</term>
|
||||
<listitem>
|
||||
<para>
|
||||
OPTIONAL. Specifies the name of the file where log messages should
|
||||
be written to. If not specified, log messages are sent to the
|
||||
application's standard output. The value must be a relative file
|
||||
name without any path components.
|
||||
</para>
|
||||
<para>
|
||||
The default value is specified by the DC-API when it creates the
|
||||
work unit and generally it should not be overridden.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>SendCfgKeys</term>
|
||||
<listitem>
|
||||
<para>
|
||||
OPTIONAL. Specifies a <literal>;</literal>-separated list of
|
||||
configuration keys that should be sent to the client application
|
||||
when a work unit is created. <literal>LogLevel</literal> and
|
||||
<literal>LogFile</literal> are always included so those should not
|
||||
be listed.
|
||||
</para>
|
||||
<para>
|
||||
The client application may use the <link
|
||||
linkend="DC_getCfgStr">DC_getCfgStr()</link>, <link
|
||||
linkend="DC_getCfgInt">DC_getCfgInt()</link>, and <link
|
||||
linkend="DC_getCfgBool">DC_getCfgBool()</link> functions to
|
||||
access the values of the keys specified by
|
||||
<literal>SendCfgKeys</literal>
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
</sect3>
|
||||
|
||||
</sect2>
|
||||
|
||||
</sect1>
|
||||
<!-- vim: set ai sw=2 tw=80: -->
|
||||
|
|
@ -7,6 +7,19 @@
|
|||
<title>DC-API Manual</title>
|
||||
</bookinfo>
|
||||
|
||||
<chapter id="general">
|
||||
<title>General information</title>
|
||||
<xi:include href="intro.xml"/>
|
||||
<xi:include href="config.xml"/>
|
||||
</chapter>
|
||||
|
||||
<chapter id="backends">
|
||||
<title>Backend-specific information</title>
|
||||
<xi:include href="boinc.xml"/>
|
||||
<!-- <xi:include href="condor.xml"/> -->
|
||||
<!-- <xi:include href="local.xml"/> -->
|
||||
</chapter>
|
||||
|
||||
<chapter id="reference">
|
||||
<title>Reference</title>
|
||||
<xi:include href="xml/dc_common.xml"/>
|
||||
|
|
@ -14,4 +27,4 @@
|
|||
<xi:include href="xml/dc.xml"/>
|
||||
</chapter>
|
||||
</book>
|
||||
<!-- vim: set ai sw=2: -->
|
||||
<!-- vim: set ai sw=2 tw=80: -->
|
||||
|
|
|
|||
|
|
@ -0,0 +1,45 @@
|
|||
<?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>
|
||||
<title>Introduction</title>
|
||||
|
||||
<para>
|
||||
The DC-API was created by MTA SZTAKI to allow easy implementation and
|
||||
deployment of distributed applications on multiple grid environments.
|
||||
</para>
|
||||
<para>
|
||||
In order to accomodate the needs of very different grid environments, the
|
||||
DC-API supports only a restricted master-worker programming model. The
|
||||
restrictions include:
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>
|
||||
Master-worker concept: there is a designated
|
||||
<emphasis>master</emphasis> process running somewhere on the grid
|
||||
infrastructure. The master process can submit worker processes called
|
||||
<emphasis>work units</emphasis>.
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
Every work unit is a sequential application.
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
There is support for limited messaging between the master and the
|
||||
running work units. It can be used to send status and control
|
||||
messages, but it is not suitable for parallel programming.
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
There can not be any direct communication between work units.
|
||||
</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</para>
|
||||
|
||||
</sect1>
|
||||
<!-- vim: set ai sw=2 tw=80: -->
|
||||
Loading…
Reference in New Issue