Validator Program

From Unofficial BOINC Wiki

Contents 1 General 2 Command-line Arguments 3 UCB Source 4 Copyright ©

[edit] General

In a BOINC Powered Project, Validation is the process of comparing Redundant Results and deciding which is to be considered correct. Because the exact numeric values calculated with Floating-Point Arithmetic varies between the various possible Platforms, this decision MUST BE application-specific.

A Validator is a Back-End Program that does validation and credit-granting. You must supply a Validator for each Application in your Project. The BOINC System Software supplies a framework program named validator.C. To make a Validator Program, you must link validator.C with two application-specific functions:

int check_set(vector<RESULT> results, DB_WORKUNIT& wu, int& canonicalid, double& credit, bool& retry);

• check_set() takes a set of results (all with outcome=SUCCESS). It reads and compares their output files. 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 Work Unit.
• If, when an output file for a Result has a nonrecoverable error (e.g. the directory is there but the file isn't, or the file is present but has invalid contents), then it must set the result's outcome (in memory, not database) to outcome=RESULT_OUTCOME_VALIDATE_ERROR and validate_state=VALIDATE_STATE_INVALID.

Note: use BOINC's Back-End Utility Functions to get file pathnames and to distinguish recoverable and nonrecoverable file-open errors.

• If a canonical result is found, check_set() must set the validate_state field of each non-ERROR result (in memory, not database) to either validate_state=VALIDATE_STATE_VALID or validate_state=VALIDATE_STATE_INVALID.
• 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 processed again in a few hours.
• check_set() should return nonzero if a major error occurs. This tells the validator to write an error message and exit.

int check_pair(RESULT& new_result, RESULT& canonical_result, bool& retry);

• The check_pair() function compares a new result to the Canonical Result. In the absence of errors, it sets the new result's validate_state to either VALIDATE_STATE_INVALID or VALIDATE_STATE_VALID.
• If it has a nonrecoverable error reading an output file of either Result, or if the new result's output file is invalid, it must set the new result's outcome (in memory, not database) to VALIDATE_ERROR.
• 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.
• The check_pair() function should return nonzero if a major error occurs. This tells the validator to write an error message and exit.

Neither function should delete files or access the BOINC Database.

Note:

See this file for a more detailed description/pseudo-code.

Two example validators are supplied (each implements check_set() and check_pair()):

• sample_bitwise_validator requires a strict majority, and regards results as equivalent only if they agree byte for byte.
• sample_trivial_validator regards any two results as equivalent if their CPU Time exceeds a given minimum.

A placeholder, validator_placeholder.C is also provided. You can replace this file with your own code and 'make' will correctly build and link it.

[edit] Command-line Arguments

A validator has the following command-line arguments:

-app appname	Name of the application
[ -one_pass_N_WU N ]	Validate at most N WUs, then exit
[ -one_pass ]	Make one pass through WU table, then exit
[ -mod n i ]	Process only WUs with (id mod n) == i. This option lets you run multiple instances of the Validator for increased performance.

[edit] UCB Source

• Validation

[edit] Copyright ©

• 2005 University of California
• 2005 Paul D. Buck

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation.