*** empty log message ***

svn path=/trunk/boinc/; revision=3979

doc/api.php

@@ -3,34 +3,30 @@ require_once("docutil.php");
 page_head("The BOINC application programming interface (API)");
 echo "
 <p>
-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 <a href=graphics.php>separately</a>.
+<p>
+BOINC applications may generate graphics,
+allowing them to provide a screensaver.
+This API is described <a href=graphics.php>here</a>.
+<p>
+BOINC applications may consist of several programs that are
+executed in sequence;
+the API for this is described <a href=compound_app.php>here</a>.
+
 
 <h3>Initialization and termination</h3>
 The application must call
 <pre>
-    int boinc_init(bool is_worker=true);
+    int boinc_init();
 </pre>
 before calling other BOINC functions or doing I/O.
-<p>
-If <code>is_worker</code> is true,
-the application will periodically report CPU time and fraction_done to
-the BOINC core client.
-<p>
-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).
-<p>
 When the application has completed it must call
 <pre>
-    int boinc_finish(int status, is_worker=true);
+    int boinc_finish(int status);
 </pre>
 <code>status</code> is nonzero if an error was encountered.
-<code>is_worker</code> is true iff it was true for boinc_init.
 This call does not return.
 
 <h3>Resolving file names</h3>
@@ -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 "
 <p>

doc/compound_app.php

@@ -7,11 +7,11 @@ echo "
 <h3>Compound applications</h3>
 
 A <b>compound application</b> consists of a <b>main program</b>
-and one or more <b>subsidiary programs</b>.
-The main program executes the subsidiary programs in sequence.
+and one or more <b>worker programs</b>.
+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.
 
 
 <p>
-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.
+
 <pre>
+struct BOINC_OPTIONS {
+};
+<p>
+The main program logic is as follows:
+<pre>
+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