Added documentation

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

doc/api.html

@@ -90,6 +90,47 @@ refresh period passed via <tt>boinc_init</tt> in <tt>APP_IN</tt>.
 <p>
 </li>
 <li>
+<b>The APP_IN Structure</b>
+<br>
+Members:
+<ul>
+	<li>
+    <tt>char app_prefrences[4096];</tt>
+	</li><li>
+    <tt>APP_IN_GRAPHICS graphics;</tt>
+	</li><li>
+    <tt>double checkpoint_period;</tt>
+	</li><li>
+    <tt>double poll_period;</tt>
+        </li><li>
+    <tt>double cpu_time;</tt>
+	</li>
+</ul>
+<br>
+The APP_IN structure is passed via <tt>boinc_init()</tt> on initialization. 
+The <tt>app_preferences</tt> string contains any user preferences. The <tt>graphics</tt> structure
+contains information about the OpenGL graphics settings. The api will initialize
+timers such that the period of <tt>time_to_checkpoint()</tt> is <tt>checkpoint_period</tt>. The <tt>poll_period</tt> states how often the core client will poll the application for state information. The <tt>cpu_time</tt> member contains the number of seconds previously spent working on the current work unit. 
+<p>
+</li>
+<li>
+<b>The APP_OUT Structure</b>
+<br>
+Members: 
+<ul>
+	<li>
+    <tt>double percent_done;</tt>
+	</li><li>
+    <tt>double cpu_time_at_checkpoint;</tt>
+	</li><li>
+    <tt>bool checkpoint_completed;</tt>
+	</li>
+</ul>
+<br>
+The APP_OUT structure is passed via <tt>checkpoint_completed()</tt> and <tt>app_completed()</tt>. The only member expected to be filled in by the application is <tt>percent_done</tt>. THe other members will be filled in by the api. The <tt>cpu_time_at_checkpoint</tt> contains the cpu time elapsed in this instance of the application, which can be combined with the <tt>cpu_time</tt> from the APP_IN structure for total cpu time spent on this work unit. 
+<p>
+</li>
+<li>
 <b>The MFILE Class</b>
 <br>
 Functions:
@@ -170,4 +211,4 @@ When the application has completed it should call <tt>app_completed()</tt>, then
 the core client that the application has completed, and closing OpenGL windows.
 <p>
 </li>
-</ol>
+</ol>

doc/client_debug.html

@@ -5,7 +5,13 @@
 The core client writes error messages to stderr.
 This mechanism is reserved for serious problems,
 i.e. those that reflect bugs in the core client program
-or conditions that require user intervention.
+or conditions that require user intervention. Specifically, 
+The client verifies that arguments to functions have valid
+values, and will print a message to stderr on an invalid argument. 
+These error messages are formatted as <tt>error: CLASS_NAME.function: 
+error_statement argument</tt>. Common errors of this type include 
+unexpected NULL pointer arguments and negative lengths. Error numbers are
+defined in <b>lib/error_numbers.h</b>.
 
 <p>
 In addition, the core client can write a variety of "logging"

doc/flow.html

@@ -11,11 +11,12 @@ the <b>high-water mark</b> and the <b>low-water mark</b>
 
 <p>
 Normally the work remaining is between the high- and low-water marks.
-Then the work remaining reaches the low-water mark,
+When the work remaining reaches the low-water mark,
 the core client contacts one or more scheduling servers,
 and attempts to get enough work to exceed the high-water mark. The
-scheduling server sends a minimum of one hour of work and a maximum of
-four weeks of work. 
+scheduling server sends a maximum of four weeks of work. If a work unit is
+not feasible for a host because it consumes too many system resources, 
+the scheduling server will not send that work unit. 
 
 <p>
 The amount of work (measured in FP/int ops) sent

doc/index.html

@@ -53,7 +53,7 @@
 
 <li><a href=sched_policy.html>Scheduling server: policy</a>
 <li><a href=sched_impl.html>Scheduling server: implementation</a>
-<li><a href=sched_impl.html>Scheduling server: debugging</a>
+<li><a href=sched_debug.html>Scheduling server: debugging</a>
 
 <li><a href=host_measure.html>Host measurements</a>
 

doc/protocol.html

@@ -112,6 +112,18 @@ Reply elements include
 <pre>
 &lt;request_delay>10&lt;/request_delay>
 &lt;message priority="low">no work available&lt;/message>
+&lt;code_sign_key>
+    1024
+    ec8b7f60fa494ce65d70afa98f91f2ab08fb5fac3931a27524e0eb954d587846
+    29e94ce79d61f4d4bc4f9660578a06e941ca271646f11ef4d2be67f4a155e0a9
+    9908b6c814d08f0f59e9dc85afcc9d65f89a33d329d963e3fd359351ee25ca7f
+    71c3bd49a88ae609152559984b3fd7cdc4937d416a43c3357a59e7ed6cf3d30d
+    0000000000000000000000000000000000000000000000000000000000000000
+    0000000000000000000000000000000000000000000000000000000000000000
+    0000000000000000000000000000000000000000000000000000000000000000
+    0000000000000000000000000000000000000000000000000000000000010001
+    .
+&lt;/code_sign_key>
 &lt;prefs_mod_time>123123&lt;/prefs_mod_time>
 &lt;preferences>
     &lt;low_water_days>1.2&lt;/low_water_days>

doc/sched_debug.html

@@ -1,3 +1,7 @@
 <h2>Scheduling server: debugging</h2>
 
 <p>
+The scheduling server uses assert to verify that arguments to functions have
+valid values. Specifically, assert statements are used to verify that pointers
+are not NULL and lengths are greater than zero. Error messages are also printed
+to stderr, which is routed by Apache to the error log. 

doc/sched_policy.html

@@ -1,4 +1,17 @@
 <h2>Scheduling server: policy</h2>
 
 <p>
-
+The scheduling server will attempt to send enough work to excede a hosts high
+water mark. If the amount of work the scheduling server is sending excedes four
+weeks, the scheduling server will not attach more work to a scheduler reply. 
+This does not prevent the scheduling server from sending a work unit that takes
+more than four weeks, but merely from attaching more work after a scheduler
+reply has four weeks of work. If a work unit uses more disk resources than a
+host has available, the scheduling server will not attach that work unit. The
+scheduling server estimates the amount of time a work unit will take to
+complete with the formula <b>(number of fpops)/(fpops per second)+(number of
+iops)/(iops per second)</b>. The number of fpops and number of iops are 
+provided by the backend when creating the work unit, and the calculation speeds
+are included in a scheduler request. If no work is available, the scheduling
+server sends the message <tt>no work available</tt> with priority <tt>low</tt>,
+and requests that the client wait before sending another scheduler request. 

doc/test.html

@@ -23,10 +23,12 @@ for initializing and testing the entire system:
 <li> <b>test_concat.php</b>: tests I/O connection using command-line args
 and filenames.
 <li> <b>test_uc_slow.php</b>: tests checkpoint/restart.
-You have to run the client yourself;
+You have to run the client yourself,
 kill and restart it a few times.
 <li> <b>test_prefs.php</b>: tests some aspects of preferences.
 <li> <b>test_api.php</b>: tests to ensure the api is working properly.
+<li> <b>test_water.php</b>: tests some aspects of water marks.
+<li> <b>test_rsc.php</b>: tests that scheduling server only sends feasable work units. 
 </ul>
 
 <p>