From 930ffe6812cb7c81d415cf7660a836d7f5ba1423 Mon Sep 17 00:00:00 2001
From: David Anderson <davea@ssl.berkeley.edu>
Date: Tue, 2 Mar 2004 03:46:04 +0000
Subject: [PATCH] *** empty log message ***

svn path=/trunk/boinc/; revision=3018
---
 checkin_notes                           |  6 ++
 client/gui_rpc_server.C                 | 16 ++---
 doc/anonymous_platform.php              |  9 +--
 doc/build_client.php                    | 39 ++++++-----
 doc/build_client_mac.php                | 23 -------
 doc/build_client_unix.php               | 21 ------
 doc/build_client_win.php                | 36 ----------
 doc/contact.php                         |  2 +-
 doc/database_setup.php                  |  1 -
 doc/gui_rpc.php                         |  2 +-
 doc/key_setup.php                       |  2 +-
 doc/ssl_client_release_instructions.txt | 32 ++++-----
 doc/test.php                            |  2 +-
 doc/tool_update_versions.php            | 56 +++++++++++-----
 doc/tool_upgrade.php                    |  1 +
 doc/tools.php                           | 26 --------
 doc/trickle.php                         | 87 +++++++++++++++++++++----
 17 files changed, 170 insertions(+), 191 deletions(-)
 delete mode 100644 doc/build_client_mac.php
 delete mode 100644 doc/build_client_unix.php
 delete mode 100644 doc/build_client_win.php

diff --git a/checkin_notes b/checkin_notes
index c1bbf17c9a..afba6e6918 100755
--- a/checkin_notes
+++ b/checkin_notes
@@ -10211,3 +10211,9 @@ Rom    Mar 1 2004
         log_flags.c
     lib/
         filesys.C, .h
+
+David  Mar 1 2004
+    - compile errors
+
+    client/
+        gui_rpc_server.C
diff --git a/client/gui_rpc_server.C b/client/gui_rpc_server.C
index 81107abf40..2d1cab8c02 100644
--- a/client/gui_rpc_server.C
+++ b/client/gui_rpc_server.C
@@ -166,7 +166,6 @@ static void handle_set_proxy_settings(char* buf, FILE* fout) {
 }
 
 int GUI_RPC_CONN::handle_rpc() {
-#ifndef _WIN32
     char buf[1024];
     int n;
 
@@ -200,7 +199,6 @@ int GUI_RPC_CONN::handle_rpc() {
         fprintf(fout, "<unrecognized/>\n");
     }
     fflush(fout);
-#endif
    return 0;
 }
 
@@ -221,16 +219,15 @@ void GUI_RPC_CONN_SET::init(char* path) {
 #ifdef _WIN32
 	addr.sa_family = AF_UNIX;
 	strcpy(addr.sa_data, path);
-#else
-    addr.sun_family = AF_UNIX;
-    strcpy(addr.sun_path, path);
-//#endif
 	WSADATA wsdata;
 	WORD wVersionRequested = MAKEWORD(1, 1);
 	WSAStartup(wVersionRequested, &wsdata);
+#else
+    addr.sun_family = AF_UNIX;
+    strcpy(addr.sun_path, path);
+#endif
     lsock = socket(AF_UNIX, SOCK_STREAM, 0);
     if (lsock < 0) {
-		int x = WSAGetLastError();
         perror("socket");
         exit(1);
     }
@@ -244,13 +241,9 @@ void GUI_RPC_CONN_SET::init(char* path) {
         perror("listen");
         exit(1);
     }
-#endif
 }
 
 bool GUI_RPC_CONN_SET::poll() {
-#ifdef _WIN32
-    return false;
-#else
     unsigned int i;
     fd_set read_fds, error_fds;
     int sock, n, retval;
@@ -298,5 +291,4 @@ bool GUI_RPC_CONN_SET::poll() {
         iter++;
     }
     return (n != 0);
-#endif
 }
diff --git a/doc/anonymous_platform.php b/doc/anonymous_platform.php
index cc7981d80f..b816ad6401 100644
--- a/doc/anonymous_platform.php
+++ b/doc/anonymous_platform.php
@@ -42,10 +42,11 @@ Here's how it works:
 
 <ul>
 <li>
-Download the source code for the BOINC core client,
-and for the project's applications,
-and compile them for your computer.
-Or download the programs from a server of your choosing.
+Download the source code for the BOINC core client
+and the project's applications, and compile them on your computer
+(instructions for compiling the core client are
+<a href=build_client.php>here</a>).
+Or download executables from a server of your choosing.
 <li>
 Run the core client and attach to the project.
 This will create a 'project directory'
diff --git a/doc/build_client.php b/doc/build_client.php
index b678736c4f..7ce24cdbc5 100644
--- a/doc/build_client.php
+++ b/doc/build_client.php
@@ -1,26 +1,29 @@
-<? // -*-html -*-
+<?
 require_once("docutil.php");
 page_head("Building the BOINC core client");
-?>
+echo "
+<p>
+It may not be necessary to build the core client;
+you can get executables for many platforms at
+<a href=http://boinc.berkeley.edu>http://boinc.berkeley.edu</a>.
+<p>
+See the <a href=software.php>Software Prerequisites</a>.
 
-For each platform your project supports (e.g.: i686-pc-linux,
-sun-sparc-solaris2.7, sun-sparc-solaris2.8, intelx86_windows),
-you must compile the core client.
+<h3>Unix, Mac OS/X</h3>
+<p>
+<pre>
+   cd boinc/client
+   make
+</pre>
+The final target is <code>boinc/client/boinc_VERSION_PLATFORM.gz</code>.
 
-<ul>
-  <li><a href=build_client_unix.php>Building the core client for Unix</a>
-  <li><a href=build_client_win.php>Building the core client GUI for Windows</a>
-  <li><a href=build_client_mac.php>Building the core client GUI for Macintosh</a>
-</ul>
+<h3>Windows</h3>
 
-The BOINC server keeps track of core client platforms and versions so that
-users may download the latest version.
-For each client compiled,
-put the package in the master server's <code>boinc/apps/</code> directory
-and run <code>boinc/tools/update_versions</code>.
-For Windows and Macintosh, the files are self-extracting executables;
-for Unix they are .gz files which can be run directly after ungzipping.
+<p>
+Open boinc.dsw (MSVC6) or boinc.sln (MSVC7).
+Build either the Release or Debug version.
+This should also build libraries and screensaver.
 
-<?
+";
    page_tail();
 ?>
diff --git a/doc/build_client_mac.php b/doc/build_client_mac.php
deleted file mode 100644
index d6dde9b9b9..0000000000
--- a/doc/build_client_mac.php
+++ /dev/null
@@ -1,23 +0,0 @@
-<? // -*-html -*-
-require_once("docutil.php");
-page_head("Building the BOINC Core Client GUI for Macintosh");
-?>
-
-See the <a href=software.php>Software Prerequisites</a>.
-
-<p>
-The build is same as for Unix.
-
-<h3>Notes</h3>
-
-CAUTION: Stuffit Expander has a default option to convert the format of text
-files to use Macintosh line endings ('\r' only).  Many of the source files
-involved here are cross-platform files, and have Unix line endings.  If you
-use Stuffit Expander to expand compressed source files, be sure to turn off
-this feature as follows: Double click on Stuffit Expander, and select File /
-Preferences....  Under cross-platform, select NEVER Convert text files to
-Macintosh format.
-
-<?
-   page_tail();
-?>
diff --git a/doc/build_client_unix.php b/doc/build_client_unix.php
deleted file mode 100644
index 3a3763496b..0000000000
--- a/doc/build_client_unix.php
+++ /dev/null
@@ -1,21 +0,0 @@
-<? // -*-html -*-
-require_once("docutil.php");
-page_head("Building the BOINC Core Client for Unix");
-?>
-
-See the <a href=software.php>Software Prerequisites</a>.
-
-<p>
-To build the core client:
-
-<pre>
-  cd boinc/client
-  make
-</pre>
-
-Easy :) The final target
-is <code>boinc/client/boinc_VERSION_PLATFORM.gz</code>.
-
-<?
-   page_tail();
-?>
diff --git a/doc/build_client_win.php b/doc/build_client_win.php
deleted file mode 100644
index 076088ea47..0000000000
--- a/doc/build_client_win.php
+++ /dev/null
@@ -1,36 +0,0 @@
-<? // -*-html -*-
-require_once("docutil.php");
-page_head("Building the BOINC Core Client GUI for Windows");
-?>
-
-See the <a href=software.php>Software Prerequisites</a>.
-
-<h2>Build executables</h2>
-
-Using MSVC6, build "boinc_GUI - Win32 Release" or "boinc_GUI - Win32 Debug"
-versions as appropriate.  This should also build dependent libraries and
-screen saver.
-
-<h2>Build installation package</h2>
-
-Open BOINC.ipr.  Update the version number:
-<ul>
-  <li>Readme.txt, license.txt
-  <li>Resources
-</ul>
-
-Execute "Build Default Media".
-
-<h2>Create self-extracting executable</h2>
-
-Open BOINC.pfw.  Accept all defaults, updating version number.
-
-<h2>Anti-virus</h2>
-
-Run a virus checker over all the individual (uncompressed)
-files as well as the final build
-
-
-<?
-   page_tail();
-?>
diff --git a/doc/contact.php b/doc/contact.php
index 16155bf753..3a8066b2c3 100644
--- a/doc/contact.php
+++ b/doc/contact.php
@@ -8,7 +8,7 @@ at the University of California, Berkeley,
 and is led by <a href=mailto:davea@ssl.berkeley.edu>Dr. David P. Anderson</a>.
 <p>
 If you have problems with the BOINC software for Windows please email
-<a href=mailto:walton_rom@msn.com>Rom Walton</a>.
+<a href=mailto:rwalton@ssl.berkeley.edu>Rom Walton</a>.
 <p>
 BOINC developers include:
 <p>
diff --git a/doc/database_setup.php b/doc/database_setup.php
index 11032feea3..b0f3cdb813 100644
--- a/doc/database_setup.php
+++ b/doc/database_setup.php
@@ -2,7 +2,6 @@
 require_once("docutil.php");
 page_head("Setting up a BOINC database");
 echo "
-<body bgcolor=ffffff>
 <h2>Setting up a BOINC database</h2>
 <p>
 Each BOINC project uses a relational database to keep track of
diff --git a/doc/gui_rpc.php b/doc/gui_rpc.php
index 23560973aa..ec1246e10d 100644
--- a/doc/gui_rpc.php
+++ b/doc/gui_rpc.php
@@ -95,7 +95,7 @@ These define a class <code>GUI_RPC</code>
 that manages the establishment of the RPC pipe,
 and that parses the returned XML into a data structure
 from which the GUI can be generated.
-The project <code>gui_test.C</code> shows how to user this mechanism.
+The project <code>gui_test.C</code> shows how to use this mechanism.
 ";
 page_tail();
 ?>
diff --git a/doc/key_setup.php b/doc/key_setup.php
index 19dadaf12d..448a5a0a5a 100644
--- a/doc/key_setup.php
+++ b/doc/key_setup.php
@@ -6,7 +6,7 @@ echo "
 
 
 The following commands generate the file upload and code signing key pairs.
-BOINC_KEY_DIR is the directory where the kays will be stored.
+BOINC_KEY_DIR is the directory where the keys will be stored.
 The code signing private key should be stored only on
 a highly secure (e.g., a disconnected, physically secure) host.
 <pre>
diff --git a/doc/ssl_client_release_instructions.txt b/doc/ssl_client_release_instructions.txt
index 7bf00faf2b..0620587c5a 100644
--- a/doc/ssl_client_release_instructions.txt
+++ b/doc/ssl_client_release_instructions.txt
@@ -1,8 +1,11 @@
-;; $Id$
+Generating and releasing core client installers
 
-<verno> represents the new version number. At the time of this update, the
-latest version was 2.17, so the new version number would be 2.18. Substitute
-2.18 everywhere you see <verno>
+
+
+<verno> represents the new version number.
+At the time of this update, the latest version was 2.17,
+so the new version number would be 2.18.
+Substitute 2.18 everywhere you see <verno>
 
 Required:
   Unix/Linux/Mac:
@@ -18,15 +21,11 @@ Required:
     InstallShield 5.5 Pro
     InstallShield Package for the Web v2
 
-     boinc\win_build\installer\Media folder
-      (copy from quarl or gmg build folders if you're starting a new
-       build folder. This should be checked in once the required files
-       are separated from the generated files)
-
+    boinc\win_build\installer\Media folder
 
 Administrivia:
     do this on a unix machine:
-    (note: the make in your default path must be gnu make,
+    (note: the make in your default path must be gmake
     IN BOTH YOUR NORMAL SHELL AND SH
     or else set-version will fail towards the end)
 
@@ -57,14 +56,11 @@ Build
     Use the HP Kayak windows box (bart) in 329 or the Dell (skinner) in 325.
 
     set up:
-        bart: Open 'quarl' on the desktop.
-        skinner: Open 'build' on the desktop.
-        other:
-            check out new source tree
-            copy Media.zip into win_build/installer; unzip
-            make sure "Media" is at top level of installer
-            Right-click on top BOINC folder;
-            CVS/preferences/policy; clear "prune empty folders" checkbox
+        check out new source tree
+        copy Media.zip into win_build/installer; unzip
+        make sure "Media" is at top level of installer
+        Right-click on top BOINC folder;
+        CVS/preferences/policy; clear "prune empty folders" checkbox
         copy "client/win/dbghelp.dll" to "win_build/Build/Debug"
 
     Open 'BOINC'
diff --git a/doc/test.php b/doc/test.php
index 87772e010c..ab334172f8 100644
--- a/doc/test.php
+++ b/doc/test.php
@@ -108,7 +108,7 @@ output is as expected).
       that the filesize never decreases along interrupted transfers.</tr>
   <tr><td><code>test_masterurl_failure.py</code></td>
     <td> tests the exponential backoff
-      mechanism on the client in case of master IURL failures.  This test is
+      mechanism on the client in case of master URL failures.  This test is
       not automated.  It has to be run, and then client.out (in the host
       directory) must be looked at to examine whether everything is working
       correctly.</tr>
diff --git a/doc/tool_update_versions.php b/doc/tool_update_versions.php
index ea4adf1bac..616dba0011 100644
--- a/doc/tool_update_versions.php
+++ b/doc/tool_update_versions.php
@@ -1,26 +1,21 @@
-<? // -*- html -*-
-   // $Id$
-   require_once("docutil.php");
-   page_head("update_versions");
-   echo "
+<?
+require_once("docutil.php");
+page_head("update_versions");
+echo "
+
+<h3>Releasing application versions</h3>
 
 <code>update_versions</code>
-releases new core client and application versions.
-Core client versions will be visible to participants
-on the 'Download BOINC' web page.
-Application versions will be distributed to participants.
-Make sure to test versions before releasing them!
+releases new application versions.
+It makes the needed database entries and copies files
+to the download directory,
+from where they will be distributed to participants.
 <p>
 To use:
 <ul>
 <li> Create an 'apps directory' under the project directory.
-Add an
-";
-echo htmlspecialchars("<app_dir>");
-echo "
-element to config.xml giving the path of the apps directory.
-<li> Create a subdirectory 'boinc' in the apps directory.
-Put new core client versions here.
+Add an ", htmlspecialchars("<app_dir>"),
+" element to config.xml giving the path of the apps directory.
 <li> Create a subdirectory for each application,
 with the same name as the application.
 Put new application versions here.
@@ -44,6 +39,33 @@ Platform strings must match the names of platforms in the database.
 <p>
 TO DO: check for code signature files.
 
+<h3>Multiple-file application versions</h3>
+
+Application versions can consist of multiple files.
+Follow the above procedure, but create a directory
+with the given name, and put the files in that directory.
+The executable file with the lexicographically first name
+will be treated as the main program.
+
+
+<h3>Releasing core client versions</h3>
+
+The same mechanism is used to release core client versions:
+Create a subdirectory 'boinc' in the apps directory,
+put new core client installer files there, and run update_versions.
+Core client versions will be visible to participants
+on your project's 'Download BOINC' web page.
+
+<p>
+<b>NOTE</b>: the files distributed in this way are installers,
+not executables.
+Instructions for creating installers are
+<a href=ssl_client_release_instructions.txt>here</a>.
+<p>
+<b>NOTE</b>: in the interests of consistency,
+we recommend that BOINC projects not distribute core client versions,
+but rather set the 'Download BOINC' link on their web page
+to point to the download page on the main BOINC site.
 
 ";
    page_tail();
diff --git a/doc/tool_upgrade.php b/doc/tool_upgrade.php
index d783afe933..6657fbbbb5 100644
--- a/doc/tool_upgrade.php
+++ b/doc/tool_upgrade.php
@@ -10,6 +10,7 @@ echo "
     <p>
     <b>upgrade</b> does the following:
     <ul>
+    <li>
     It copies files from the source/html/* directories
     to the corresponding project directories.
     <li>
diff --git a/doc/tools.php b/doc/tools.php
index 3e7afa8b30..d49b0c947d 100644
--- a/doc/tools.php
+++ b/doc/tools.php
@@ -2,32 +2,6 @@
 require_once("docutil.php");
 page_head("Operational Tools");
 echo "
-BOINC provides tools for creating and operating projects:
-<p>
-<table border=1 cellpadding=8 width=100%>
-  <tr><td><code>boinc/tools/</code></td>
-      <td><a href=make_project.php><code>make_project</code></a> </td>
-      <td>Creates the server complex for a new project.</td>
-  </tr>
-  <tr><td><code>boinc/sched/</code></td><td> <a
-  href=tool_start.php><code>start, stop, status</code></a> </td> <td>
-      BOINC start / Super Cron program
-  </td></tr>
-  <tr><td><code>boinc/tools/</code></td><td> <a href=tool_add.php><code>add</code></a> </td> <td>
-      Adds objects to the database through command-line. 
-  </td></tr>
-  <tr><td><code>boinc/tools/</code></td><td> <a href=tool_xadd.php><code>xadd</code></a> </td> <td>
-      Adds objects to the database through project.xml.
-  </td></tr>
-  <tr><td><code>boinc/tools/</code></td><td> <a href=tool_update_versions.php><code>update_versions</code></a> </td> <td>
-      Adds core and application versions to the database.
-  </td></tr>
-  <tr><td><code>boinc/tools/</code></td><td> <a href=><code>upgrade</code></a> </td> <td>
-      Upgrades an existing installation
-  </td></tr>
-</table>
-<p>
-
 Projects can create their own tools using the Python API (see <a
 href=python.php>Python framework</a>) or the C++ API (<code>db/db.h</code>)
 <p>
diff --git a/doc/trickle.php b/doc/trickle.php
index 7d304a3cc7..b722e49602 100644
--- a/doc/trickle.php
+++ b/doc/trickle.php
@@ -9,29 +9,81 @@ let applications communicate with the server
 during the execution of a workunit.
 That are intended for applications that have
 long work units (multiple days).
+Trickle messages may be in either direction
+(application to server, or vice versa).
 Typical uses of this mechanism:
 <ul>
-<li> The application reports its current CPU usage,
+<li>
+The application reports its current CPU usage,
 so that users can be granted incremental credit
 (rather than waiting until the end of the work unit).
-<li> The application reports a summary of the computational state,
+
+<li>
+The application reports a summary of the computational state,
 so that server logic can decide if the computation should be aborted.
 </ul>
 
 <p>
-Trickle messages are asynchronous and unreliable.
-A trickle message may not be delivered immediately
-after it is generated by the application.
-If additional trickle messages are generated during the interval,
-only the last one will be sent.
-Thus, the content of trickle messages should be cumulative
-rather than incremental.
+Trickle messages are asynchronous and reliable.
+A trickle message may not be delivered immediately after it is sent.
+If there is a message waiting to be sent,
+the BOINC client may contact the scheduling server,
+but this may take a while if the client is offline.
+
+
+<p>
+
+
+<h3>API (client)</h3>
+
+<pre>
+<code>int boinc_send_trickle(char*)</code>
+</pre>
+sends a trickle message.
+Returns zero if success.
+<p>
+<pre>
+<code>bool boinc_receive_trickle(char* buf, int len)</code>
+</pre>
+receives a trickle message.
+Returns true if there was a message.
+Messages are delivered in order.
+
+<h3>API (server)</h3>
+
+The server C library API:
+<pre>
+<code>
+int get_trickle_message(
+    int applicationid,
+    int& resultid,
+    int& messagid,
+    char* buf,
+    int len
+);
+
+int mark_trickle_processed(int messagid);
+
+int send_trickle_message(
+    int resultid,
+    char* buf
+);
+</code>
+</pre>
+get_trickle_message() gets an unprocessed trickle message
+for the given application,
+returning the result and message IDs as well as the message itself.
+mark_trickle_processed() flags a trickle message as processed.
+send_trickle_message() sends a trickle message to the
+client handling the given result.
+<p>
+These functions are also available as scriptable command-line programs.
 
 <h3>Implementation</h3>
 <p>
-<code>boinc_trickle()</code>
+On the client,
+<code>boinc_send_trickle()</code>
 creates a file 'trickle' in the slot directory
-(overwriting any existing file of that name)
 and signals the core client via shared memory.
 When the core client gets this signal,
 or when the application exits,
@@ -43,6 +95,19 @@ it scans the project directory for trickle files
 and includes them in the request.
 On successful RPC completion it deletes the trickle files.
 
+<p>
+boinc_receive_trickle() sets a flag in the result record;
+this flag is conveyed to the scheduling server.
+<p>
+The server database has two tables,
+trickle_to_server and trickle_to_client.
+The scheduling server extracts trickle messages from
+the request message and inserts them in trickle_to_server.
+If the above flag is set for a given result,
+it queries the trickle_to_client table for that result
+and appends any messages to the reply.
+
+
 ";
 
 page_tail();