mirror of https://github.com/BOINC/boinc.git
130 lines
4.0 KiB
PHP
130 lines
4.0 KiB
PHP
<?php
|
|
require_once("docutil.php");
|
|
page_head("Validation");
|
|
echo "
|
|
<p>
|
|
<b>Validation</b> is the process of comparing redundant results
|
|
and deciding which is to be considered correct.
|
|
Because floating-point arithmetic varies between platforms,
|
|
this decision is an application-specific.
|
|
<p>
|
|
A <b>validator</b> is a back-end program that does validation
|
|
and credit-granting.
|
|
You must supply a validator for each application in your project.
|
|
BOINC supplies a framework program <b>validator.C</b>.
|
|
This program must be linked with two application-specific functions:
|
|
<pre>",
|
|
htmlspecialchars("
|
|
int check_set(vector<RESULT> results, DB_WORKUNIT& wu, int& canonicalid, double& credit, bool& retry);
|
|
"),
|
|
"</pre>
|
|
<ul>
|
|
<li><b>check_set()</b> takes a set of results (all with outcome=SUCCESS).
|
|
If there is a quorum of matching results,
|
|
it selects one of them as the canonical result, returning its ID.
|
|
In this case it also returns the credit to
|
|
be granted for correct results for this workunit.
|
|
|
|
<li>
|
|
If, when an output file for a result has a nonrecoverable error
|
|
(i.e. the directory is there but the file isn't),
|
|
then it must set the result's outcome (in memory, not database)
|
|
to VALIDATE_ERROR.
|
|
Note: the function try_fopen() (in lib/util.C) can be used
|
|
to detect recoverable/nonrecoverable errors.
|
|
<li>
|
|
If a canonical result is found, check_set() must set the
|
|
validate_state field of each non-ERROR result to either VALID or INVALID.
|
|
|
|
<li>
|
|
If a recoverable error occurs while reading output files
|
|
(e.g. a directory wasn't visible due to NFS mount failure)
|
|
then check_set() should return retry=true.
|
|
This tells the validator to arrange for this WU to be
|
|
examined again in a few hours.
|
|
<li>
|
|
check_set() should return nonzero if a major error occurs.
|
|
This tells the validator to write an error message and exit.
|
|
</ul>
|
|
<p>
|
|
<pre>",
|
|
htmlspecialchars("
|
|
int check_pair(RESULT& new_result, RESULT& canonical_result, bool& retry);
|
|
"),
|
|
"</pre>
|
|
<ul>
|
|
<li>
|
|
<b>check_pair()</b> compares a new result to the canonical result.
|
|
In the absence of errors,
|
|
it sets the new result's validate_state to either VALID or INVALID.
|
|
<li>
|
|
If it has a nonrecoverable error reading an output file of either result,
|
|
it must set the new result's outcome (in memory, not database)
|
|
to VALIDATE_ERROR.
|
|
<li>
|
|
If it has a recoverable error while reading an output file of either result,
|
|
it returns retry=true,
|
|
which causes the validator to arrange for the WU to be examined
|
|
again in a few hours.
|
|
<li>
|
|
check_pair() should return nonzero if a major error occurs.
|
|
This tells the validator to write an error message and exit.
|
|
</ul>
|
|
|
|
<p>
|
|
Two example validators are supplied
|
|
(each implements check_set() and check_pair()):
|
|
<ul>
|
|
<li>
|
|
<b>sample_bitwise_validator</b> requires a strict majority,
|
|
and regards results as equivalent only if they agree byte for byte.
|
|
<li>
|
|
<b>sample_trivial_validator</b>
|
|
regards any two results as equivalent if their CPU time
|
|
exceeds a given minimum.
|
|
</ul>
|
|
<p>
|
|
<b>validate_util.C</b> contains support functions for
|
|
both of the above.
|
|
|
|
<hr>
|
|
<b>NOTE: the above code assumes that each result
|
|
has a single output file.
|
|
Revisions will be needed to handle multiple output files.
|
|
To do this you will need to know the following:
|
|
</b>
|
|
|
|
<p>
|
|
The database field 'result.xml_doc_out'
|
|
describes a result's output files.
|
|
It has the form
|
|
<pre>
|
|
",htmlspecialchars("
|
|
<file_info>...</file_info>
|
|
[ ... ]
|
|
<result>
|
|
<name>foobar</name>
|
|
<wu_name>blah</wu_name>
|
|
<exit_status>blah</exit_status>
|
|
<file_ref>...</file_ref>
|
|
[ ... ]
|
|
</result>
|
|
"),"
|
|
</pre>
|
|
The components are:
|
|
<ul>
|
|
<li> The <b><name></b> element is the result name.
|
|
<li> The <b><wu_name></b> element is the workunit name.
|
|
<li> Each <b><file_ref></b> element is an association to an output file,
|
|
described by a corresponding <b><file_info></b> element.
|
|
</ul>
|
|
<p>
|
|
The XML document describing the sizes and checksums of the output
|
|
files is a list of <b><file_info></b> elements,
|
|
with the <b>nbytes</b> and <b>md5_cksum</b> fields present.
|
|
The project back end
|
|
must parse this field to find the locations and checksums of output files.
|
|
";
|
|
page_tail();
|
|
?>
|