diff --git a/doc/api.php b/doc/api.php index 5514cf8a39..64e142b482 100644 --- a/doc/api.php +++ b/doc/api.php @@ -3,34 +3,30 @@ require_once("docutil.php"); page_head("The BOINC application programming interface (API)"); echo "

-The BOINC API is a set of C++ functions. +The BOINC API is a set of C functions. Unless otherwise specified, the functions return an integer error code; zero indicates success. -On an error return, the application should exit with that status. -The BOINC graphics API is described separately. +

+BOINC applications may generate graphics, +allowing them to provide a screensaver. +This API is described here. +

+BOINC applications may consist of several programs that are +executed in sequence; +the API for this is described here. +

Initialization and termination

The application must call
-    int boinc_init(bool is_worker=true);
+    int boinc_init();
 
before calling other BOINC functions or doing I/O. -

-If is_worker is true, -the application will periodically report CPU time and fraction_done to -the BOINC core client. -

-An application will detect that it is standalone if it cannot parse -the init data file, or if it cannot setup the shared memory. -A standalone application will function independently of the BOINC core client -(this is useful for testing). -

When the application has completed it must call

-    int boinc_finish(int status, is_worker=true);
+    int boinc_finish(int status);
 
status is nonzero if an error was encountered. -is_worker is true iff it was true for boinc_init. This call does not return.

Resolving file names

@@ -137,22 +133,28 @@ html_text(" int boinc_get_init_data(APP_INIT_DATA&); struct APP_INIT_DATA { - char project_preferences[4096]; + int core_version; + char app_name[256]; + char project_preferences[65536]; char user_name[256]; char team_name[256]; char project_dir[256]; char boinc_dir[256]; char wu_name[256]; char authenticator[256]; + int slot; double user_total_credit; double user_expavg_credit; double team_total_credit; double team_expavg_credit; + HOST_INFO host_info; }; "), " to get the following information: "; list_start(); +list_item("core version", "The version number of the core client"); +list_item("app_name", "The application name (from the server's DB)"); list_item("project_preferences", "An XML string containing the user's project-specific preferences."); list_item("user_name", " the user's 'screen name' on this project."); @@ -161,10 +163,12 @@ list_item("project_dir", "absolute path of project directory"); list_item("boinc_dir", "absolute path of BOINC root directory"); list_item("wu_name", "name of workunit being processed"); list_item("authenticator", "user's authenticator for this project"); +list_item("slot", "The number of the app's 'slot' (0, 1, ...)"); list_item("user_total_credit", " user's total work for this project."); list_item("user_expavg_credit", " user's recent average work per day."); list_item("team_total_credit", " team's total work for this project."); list_item("team_expavg_credit", " team's recent average work per day."); +list_item("host_info", "A structure describing the host hardware and OS"); list_end(); echo "

diff --git a/doc/compound_app.php b/doc/compound_app.php index b4374a9781..843ec3cb02 100644 --- a/doc/compound_app.php +++ b/doc/compound_app.php @@ -7,11 +7,11 @@ echo "

Compound applications

A compound application consists of a main program -and one or more subsidiary programs. -The main program executes the subsidiary programs in sequence. +and one or more worker programs. +The main program executes the worker programs in sequence. It maintains a state file that records which subsidiary programs have already completed. -It assigns to each subsidiary application +It assigns to each worker application a subrange of the overall 'fraction done' range of 0..1. For example, if there are two subsidiary applications with equal runtime, @@ -20,14 +20,24 @@ would have range 0.5 to 1.

-The main program must not call boinc_init() or boinc_finish(). -Its logic is as follows: +The BOINC API provides a number of functions, +and in developing a compound application you must decide +whether these +how these functions are to be divided between +the main and worker programs. +

+struct BOINC_OPTIONS {
+};
+

+The main program logic is as follows: +

+boinc_init_options(...)
 read state file
 for each remaining subsidiary application:
     boinc_parse_init_data_file()
-    aip.fraction_done_start = x
-    aip.fraction_done_end = y
+    aid.fraction_done_start = x
+    aid.fraction_done_end = y
     boinc_write_init_data_file()
     run the app
     write state file