From 486e704ba440e896b048a4e33fd161d36d1830ef Mon Sep 17 00:00:00 2001 From: David Anderson Date: Mon, 17 Jul 2006 16:38:53 +0000 Subject: [PATCH] *** empty log message *** svn path=/trunk/boinc/; revision=10654 --- checkin_notes | 10 + client/client_state.C | 24 +++ client/cs_apps.C | 23 --- client/gui_rpc_server.C | 10 + client/gui_rpc_server.h | 1 + doc/api.php | 66 +++--- doc/backend_programs.php | 9 +- doc/boinc_dev.php | 45 +++- doc/boinc_news.inc | 12 +- doc/configuration.php | 418 ++------------------------------------ doc/contact.php | 2 +- doc/create_project.php | 7 +- doc/docutil.php | 14 +- doc/download_other.php | 8 + doc/index.php | 384 +++++++++++++--------------------- doc/mass_email.php | 2 +- doc/poll.inc | 15 +- doc/poll.php | 3 +- doc/poll_data.inc | 31 +++ doc/projects.inc | 110 ++++++++++ doc/projects.php | 32 ++- doc/server_components.php | 7 +- doc/tool_start.php | 97 +++++---- doc/trickle.php | 56 ++--- doc/trickle_api.php | 68 +++++-- doc/white.css | 4 + html/inc/prefs.inc | 2 +- sched/trickle_handler.C | 9 +- 28 files changed, 628 insertions(+), 841 deletions(-) create mode 100644 doc/projects.inc diff --git a/checkin_notes b/checkin_notes index 67c9ff347c..6cab15bd20 100755 --- a/checkin_notes +++ b/checkin_notes @@ -7582,3 +7582,13 @@ David 14 July 2006 client_types.C,h cs_account.C cs_scheduler.C + +David 17 July 2006 + - core client: close GUI RPC listening socket on exit + + client/ + client_state.C + cs_apps.C + gui_rpc_server.C,h + sched/ + trickle_handler.C diff --git a/client/client_state.C b/client/client_state.C index eb4cc14a8b..a2390accb6 100644 --- a/client/client_state.C +++ b/client/client_state.C @@ -1401,6 +1401,30 @@ void CLIENT_STATE::network_available() { active_tasks.network_available(); } +// Quit running applications, quit benchmarks, +// write the client_state.xml file +// (in principle we could also terminate net_xfers here, +// e.g. flush buffers, but why bother) +// +int CLIENT_STATE::quit_activities() { + int retval; + + // calculate long-term debts (for state file) + // + adjust_debts(); + + retval = active_tasks.exit_tasks(); + if (retval) { + msg_printf(NULL, MSG_ERROR, + "Couldn't exit tasks: %s", boincerror(retval) + ); + } + write_state_file(); + gui_rpcs.close(); + abort_cpu_benchmarks(); + return 0; +} + // return a random double in the range [rmin,rmax) static inline double rand_range(double rmin, double rmax) { if (rmin < rmax) { diff --git a/client/cs_apps.C b/client/cs_apps.C index e65efd6f7b..d78297d932 100644 --- a/client/cs_apps.C +++ b/client/cs_apps.C @@ -45,29 +45,6 @@ using std::vector; -// Quit running applications, quit benchmarks, -// write the client_state.xml file -// (in principle we could also terminate net_xfers here, -// e.g. flush buffers, but why bother) -// -int CLIENT_STATE::quit_activities() { - int retval; - - // calculate long-term debts (for state file) - // - adjust_debts(); - - retval = active_tasks.exit_tasks(); - if (retval) { - msg_printf(NULL, MSG_ERROR, - "Couldn't exit tasks: %s", boincerror(retval) - ); - } - write_state_file(); - abort_cpu_benchmarks(); - return 0; -} - // Handle a task that has finished. // Mark its output files as present, and delete scratch files. // Don't delete input files because they might be shared with other WUs. diff --git a/client/gui_rpc_server.C b/client/gui_rpc_server.C index ceace4c6ea..b91e629784 100644 --- a/client/gui_rpc_server.C +++ b/client/gui_rpc_server.C @@ -364,4 +364,14 @@ void GUI_RPC_CONN_SET::got_select(FDSET_GROUP& fg) { } } +void GUI_RPC_CONN_SET::close() { + if (log_flags.guirpc_debug) { + msg_printf(NULL, MSG_INFO, "closing GUI RPC socket %d\n", lsock); + } + if (lsock >= 0) { + boinc_close_socket(lsock); + lsock = -1; + } +} + const char *BOINC_RCSID_88dd75dd85 = "$Id$"; diff --git a/client/gui_rpc_server.h b/client/gui_rpc_server.h index c9ff4b4fe5..d3ba2465df 100644 --- a/client/gui_rpc_server.h +++ b/client/gui_rpc_server.h @@ -56,6 +56,7 @@ public: void get_fdset(FDSET_GROUP&, FDSET_GROUP&); void got_select(FDSET_GROUP&); int init(); + void close(); bool got_recent_rpc(double interval); }; diff --git a/doc/api.php b/doc/api.php index d3ef8cc7b9..dd59ffc1f3 100644 --- a/doc/api.php +++ b/doc/api.php @@ -30,13 +30,13 @@ Initialization for graphical and compound applications are described elsewhere (see links above). Other applications must call 
-    int boinc_init();
+int boinc_init();
before calling other BOINC functions or doing I/O.

When the application has completed it must call 

-    int boinc_finish(int status);
+int boinc_finish(int status);
status is nonzero if an error was encountered. This call does not return. @@ -49,7 +49,7 @@ in the two cases. For example you might want to output debugging information if the application is running standalone. To determine if the application is running in standalone mode or under the control of the BOINC client, call 
-    int boinc_is_standalone(void);
+int boinc_is_standalone(void);
This returns non-zero (True) if the application is running standalone, and zero (False) if the application is running under the control of the BOINC client. @@ -59,24 +59,24 @@ is running under the control of the BOINC client.

Resolving file names

Applications that use named input or output files must call 
-    int boinc_resolve_filename(char *logical_name, char *physical_name, int len);
+int boinc_resolve_filename(char *logical_name, char *physical_name, int len);
or ", html_text(" - int boinc_resolve_filename_s(char *logical_name, std::string& physical_name); +int boinc_resolve_filename_s(char *logical_name, std::string& physical_name); "), " to convert logical file names to physical names. For example, instead of 
-    f = fopen(\"my_file\", \"r\");
+f = fopen(\"my_file\", \"r\");

the application might use ", html_text(" - string resolved_name; - retval = boinc_resolve_filename(\"my_file\", resolved_name); - if (retval) fail(\"can't resolve filename\"); - f = fopen(resolved_name.c_str(), \"r\"); +string resolved_name; +retval = boinc_resolve_filename(\"my_file\", resolved_name); +if (retval) fail(\"can't resolve filename\"); +f = fopen(resolved_name.c_str(), \"r\"); "), " boinc_resolve_filename() doesn't need to be used for temporary files. @@ -110,7 +110,7 @@ Frequency of checkpointing is a user preference (e.g. laptop users might want to checkpoint infrequently). An application must call 
-    int boinc_time_to_checkpoint();
+int boinc_time_to_checkpoint();
whenever it reaches a point where it is able to checkpoint. If this returns nonzero (True) then @@ -118,7 +118,7 @@ the application should checkpoint immediately (i.e., write the state file and flush all output files), then call 
-    void boinc_checkpoint_completed();
+void boinc_checkpoint_completed();
boinc_time_to_checkpoint() is fast, so it can be called frequently (hundreds or thousands of times a second). @@ -182,7 +182,7 @@ and optionally at intermediate points. The core client GUI displays the percent done of workunits in progress. To keep this display current, an application should periodically call 
-   boinc_fraction_done(double fraction_done);
+boinc_fraction_done(double fraction_done);
The fraction_done argument is an estimate of the workunit fraction complete (0 to 1). @@ -191,7 +191,7 @@ The sequence of arguments in successive calls should be non-decreasing. An application should never 'reset' and start over if an error occurs; it should exit with an error code. 
-   double boinc_get_fraction_done();
+double boinc_get_fraction_done();
returns the last value set, or -1 if none has been set (this would typically be called from graphics code). @@ -201,25 +201,25 @@ The following functions get information from the core client; this information may be useful for graphics. ", html_text(" - int boinc_get_init_data(APP_INIT_DATA&); +int boinc_get_init_data(APP_INIT_DATA&); - struct APP_INIT_DATA { - 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; - }; +struct APP_INIT_DATA { + 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: "; @@ -245,7 +245,7 @@ echo "

An application may call ", html_text(" - int boinc_wu_cpu_time(double &cpu_time); +int boinc_wu_cpu_time(double &cpu_time); "), "to get its total CPU time (from the beginning of the work unit, not just since the last restart). This excludes CPU time used to render graphics. diff --git a/doc/backend_programs.php b/doc/backend_programs.php index 3f23d559c0..3ba75790c6 100644 --- a/doc/backend_programs.php +++ b/doc/backend_programs.php @@ -1,14 +1,15 @@ A BOINC project includes of a set of daemons -(programs that run all the time). -Each program should be listed as a daemon in the +for generating and handling work. +Each program should be listed as a +daemon in the config.xml file. -They all have the command-line options: +Most daemons have the command-line options: "; list_start(); list_item("-d N", diff --git a/doc/boinc_dev.php b/doc/boinc_dev.php index a1bafc8121..a6475e6f7f 100644 --- a/doc/boinc_dev.php +++ b/doc/boinc_dev.php @@ -1,9 +1,48 @@ Writing add-on software +

+BOINC's architecture is 'open'; +documented interfaces making it possible to +develop various types of applications and web sites that +interact with BOINC's core components. +Examples include: +"; +list_start(); +list_item("Client GUIs", + "These allow an application to control a local + or remove core client." +); +list_item("Credit statistics web sites", + "Daily feeds of statistics data from BOINC projects + let you create web sites showing leaderboards." +); +list_item("Account managers", + "These interfaces support web sites that + let BOINC users manage their accounts." +); +list_item("Server status web sites", + "These interfaces support web sites showing the + server status of BOINC projects." +); +list_item("Web RPCs", + "These interfaces let a program or web site + obtain information about users and hosts from projects." +); +list_item("Local editing of preferences", + "This mechanism lets you write a program local editing of preferences." +); +list_end(); +echo " +

+An index of add-on software +is maintained by Janus Kristensen. +If you write something useful, publicize it by adding it to the index. +

Developing BOINC itself

-

Getting involved

BOINC is free software, distributed under the Lesser GNU Public License (LGPL). We are in constant need of volunteers to @@ -70,7 +109,7 @@ with lines of different colors or styles for different projects. -Please check with davea at ssl.berkeley.edu +Please check with David Anderson before undertaking any of these. "; diff --git a/doc/boinc_news.inc b/doc/boinc_news.inc index d07e720a54..60247629ed 100644 --- a/doc/boinc_news.inc +++ b/doc/boinc_news.inc @@ -2,9 +2,15 @@ $project_news = array( array("July 13, 2006", - "Coming down to Earth, - an article in the The Economist, - describes Africa@home, a recently-announced BOINC project + "We are conducting an online survey + of BOINC participants. + Please fill out the survey form - + your responses will help us improve BOINC and the projects that use it. " +), +array("July 13, 2006", + "Articles in The Economist + and WebWire + describe Africa@home, a recently-announced BOINC project that studies malaria epidemiology. Africa@home is a collaboration of the Swiss Tropical Institute, CERN, and a group of universities (three of them from Africa). diff --git a/doc/configuration.php b/doc/configuration.php index eb97fdb2bd..19a3c37755 100644 --- a/doc/configuration.php +++ b/doc/configuration.php @@ -1,430 +1,40 @@ ELEMENTS SHOULD BE CHANGED TO 1 . -// MANY OF THE TAGS BELOW ARE NOT EXPLAINED IN THE DOCUMENTATION, AND THE LIST HERE IS PROBABLY NOT COMPLETE. - require_once("docutil.php"); - page_head("The project configuration file"); echo "\n"; echo" -A project is described by a configuration file +A project's configuration is described by a file named config.xml in the project's directory. This file is created, with default values, by the make_project script. -However, you will probably need to change or add some items +However, you will need to change or add some items during the life of your project.

-A config.xml file looks like this: -

",
-htmlspecialchars("
+The format of config.xml file is:
+", html_text("
 
   
-                      project.hostname.ip   
-                   databasename          
-                   database.host.ip      
-                   database_user_name    
-                 database_password     
-                 shared_memory_key     
-              http://A/URL          
-              /path/to/directory    
-          /path/to/directory    
-           N                     
-                http://A/URL          
-                /path/to/directory    
-                   http://A/URL          
-        http://A/URL          
-                   /path/to/directory    
-
-    [  ]
-    [  ]
-    [  ]
-    [  ]
-    [  N  ]
-    [  0|1  ]
-    [  N  ]
-    [  N  ]
-    [  ]
-    [  ]
-    [  ]
-    [  N  ]
-    [  N  ]
-    [  N  ]
-    [  N  ]
-    [  N  ]
-    [  0|1  ]
-    [  0|1  ]
-    [  0|1  ]
-    [  path  ]
-    [  N  ]
-    [  X  ]
-    [  X  ]
-    [  X  ]
-    [  X  ]
-    [  ]
-    [ X ]
-    [ URL ]
-    [  ]
-    [  N  ]
-    [  N  ]
-    [  ]
-
-
-    
-      ../        
-          bin            
-      cgi-bin        
+    [ configuration options ]
   
-
   
-    
-                feeder -d 3   
-      [        hostname.ip        ]
-      [    1              ]
-    
-    
-    ...
-    
+    [ list of daemons ]
   
-
   
-    
-                get_load        
-             get_load.out    
-             5 min           
-      [        host.ip                ]
-      [    1                  ]
-      [  1                ]
-    
-    
-            echo \"HI\" | mail root@example.com     
-         /dev/null                             
-         1 day                                 
-    
-    
-    ...
-    
+    [ list of periodic tasks ]
   
 
 
-"),
-"
+")," +Details on: + "; -echo "The general project configuration elements are:"; -list_start(); -list_item("host", - "name of project's main host, as given by Python's socket.hostname(). - Daemons and tasks run on this host by default." -); -list_item("db_name", "Database name"); -list_item("db_host", "Database host machine"); -list_item("db_user", "Database user name"); -list_item("db_passwd", "Database password"); -list_item("shmem_key", "ID of scheduler shared memory. Must be unique on host."); -list_item("download_url", "URL of data server for download"); -list_item("download_dir", "absolute path of download directory"); -list_item("download_dir_alt", - "absolute path of old download directory - (see Hierarchical upload/download directories)" -); -list_item("upload_url", "URL of file upload handler"); -list_item("uldl_dir_fanout", "fan-out factor of upload and download directories - (see Hierarchical upload/download directories)" -); -list_item("upload_dir", "absolute path of upload directory"); -list_item("cgi_url", "URL of scheduling server"); -list_item("stripchart_cgi_url", "URL of stripchart server"); -list_item("log_dir", "Path to the directory where the assimilator, feeder, transitioner and -cgi output logs are stored. This allows you to change the default log -directory path. If set explicitly, you can also use the 'grep logs' -features on the administrative pages. Note: enabling 'grep logs' with -very long log files can hang your server, since grepping GB files can -take a long time. If you enable this feature, be sure to rotate the -logs so that they are not too big."); -list_item("sched_lockfile_dir", - "Enables scheduler locking (recommended) and specifies - directory where scheduler lockfiles are stored. - Must be writable to the Apache user. -"); -list_item("profile_screening", - "If present, don't show profile pictures until they've been - screened and approved by project admins." -); -list_end(); - -echo " - The following control features that you may or may not want - available to users. -"; -list_start(); -list_item("disable_account_creation", - "If present, disallow account creation" -); -list_item("show_results", - "Enable web site features that show results (per user, host, etc.)" -); -list_end(); - -echo " - The following control the way in which results are scheduled, sent, - and assigned to users and hosts. -"; -list_start(); -list_item("one_result_per_user_per_wu", - "If present, send at most one result of a given workunit to a given user. - This is useful for checking accuracy/validity of results. - It ensures that the results for a given workunit are generated by - different users. - If you have a validator that compares different results - for a given workunits to ensure that they are equivalent, - you should probably enable this. - Otherwise you may end up validating results from a given user - with results from the same user." -); -list_item("max_wus_to_send", - "Maximum results sent per scheduler RPC. Helps prevent hosts with - trouble from getting too many results and trashing them. But you - should set this large enough so that a host which is only connected to - the net at intervals has enough work to keep it occupied in between - connections." -); -list_item("non_cpu_intensive", - "If this flag is present, - project will be treated specially by the client: - - This is intended for - applications that use little CPU time, - e.g. that do network or host measurements." -); -list_item("min_sendwork_interval", - "Minimum number of seconds to wait after sending results to a given - host, before new results are sent to the same host. Helps prevent - hosts with download or application problems from trashing lots of - results by returning lots of error results. But don't set it to be so - long that a host goes idle after completing its work, before getting - new work." -); -list_item("daily_result_quota", - "Maximum number of results (per CPU) sent to a given host in a 24-hour - period. Helps prevent hosts with download or application problems from - returning lots of error results. Be sure to set it large enough that - a host does not go idle in a 24-hour period, and can download enough - work to keep it busy if disconnected from the net for a few days. The - maximum number of CPUS is bounded at four." -); -list_item("ignore_delay_bound", - "By default, results are not sent to hosts too slow to complete them within delay bound. - If this flag is set, this rule is not enforced." -); -list_item("dont_generate_upload_certificates", - "Don't put upload certificates in results. - This makes result generation a lot faster, - since no encryption is done, - but you lose protection against DoS attacks - on your upload servers." -); -list_item("locality_scheduling", - "When possible, send work that uses the same files that the host - already has. This is intended for projects which have large data - files, where many different workunits use the same data file. In - this case, to reduce download demands on the server, it may be - advantageous to retain the data files on the hosts, and send - them work for the files that they already have. - See Locality Scheduling." -); -list_item("locality_scheduling_wait_period", - "This element only has an effect when used in conjunction with the - previous locality scheduling element. It tells the scheduler to - use 'trigger files' to inform the project that more work is - needed for specific files. The period is the number of seconds - which the scheduler will wait to see if the project can create - additional work. Together with project-specific daemons or - scripts this can be used for 'just-in-time' workunit - creation. See Locality Scheduling." -); -list_item("min_core_client_version", - "If the scheduler gets a request from a client with - a version number less than this, - it returns an error message and doesn't do any other processing." -); -list_item("choose_download_url_by_timezone", - "When the scheduler sends work to hosts, it replaces the download - URL appearing in the data and executable file descriptions with - the download URL closest to the host's timezone. The project - must provide a two-column file called 'download_servers' in the - project root directory. This is a list of all download servers - that will be inserted when work is sent to hosts. The first column - is an integer listing the server's offset in seconds from UTC. - The second column is the server URL in the format such as - http://einstein.phys.uwm.edu. The download servers must - have identical file hierarchies and contents, and the path to - file and executables must start with '/download/...' as in - 'http://einstein.phys.uwm.edu/download/123/some_file_name'." -); -list_item("cache_md5_info", - "When creating work, keep a record (in files called foo.md5) of the - file length and md5 sum of data files and executables. This can - greatly reduce the time needed to create work, if (1) these files - are re-used, and (2) there are many of these files, and (3) reading - the files from disk is time-consuming." -); -list_item("min_core_client_version_announced", - "Announce a new version of the BOINC core client, which in the future - will be the minimum required version. In conjunction with the next - tag, you can warn users with version below this to upgrade by a - specified deadline. Example value: 419." -); -list_item("min_core_client_upgrade_deadline", - "Use in conjunction with the previous tag. The value given here is the - Unix epoch returned by time(2) until which hosts can update their - core client. After this time, they may be shut out of the project. - Before this time, they will receive messages warning them to upgrade." -); -list_item("nowork_skip", - "If the scheduling server has no work, - it replies to RPCs without doing any database access - (e.g., without looking up the user or host record). - This reduces DB load, but it fails to update - preferences when users click on Update. - Use it if your server DB is overloaded." -); -list_item("resend_lost_results", - "If set, and a <other_results> list is present - in scheduler request, - resend any in-progress results not in the list. - This is recommended; - it should increase the efficiency of your project" -); -list_item("min_passwd_length", - "Minimum length of user passwords. Default is 6." -); -list_item("fp_benchmark_weight", - "The weighting given to the Whetstone benchmark - in the calculation of claimed credit. - Must be in [0 .. 1]. - Projects whose applications are floating-point intensive should use 1; - pure integer applications, 0. - Choosing an appropriate value will reduce the disparity - in claimed credit between hosts. - The script html/ops/credit_study.php, - run against the database of a running project, - will suggest what value to use." -); - -list_item("default_disk_max_used_gb", "Sets the default value for - the disk_max_used_gb preference so its consistent between the - scheduler and web pages. The scheduler uses it when a request - for work doesn't include preferences, or the preference is set - to zero. The web page scripts use it to set the initial value - when displaying or editing preferences the first time, or when - the user never saved them. Default is 100. -"); - -list_item("default_disk_max_used_pct", "Sets the default value for - the disk_max_used_pct preference so its consistent between the - scheduler and web pages. The scheduler uses it when a request - for work doesn't include preferences, or the preference is set - to zero. The web page scripts use it to set the initial value - when displaying or editing preferences the first time, or when - the user never saved them. Default is 50. -"); - -list_item("default_disk_min_free_gb", "Sets the default value for - the disk_min_free_gb preference so its consistent between the - scheduler and web pages. The scheduler uses it when a request - for work doesn't include preferences. The web page scripts use - it to set the initial value when displaying or editing - preferences the first time, or when the user never saved them. - Also, the scheduler uses this setting to override any smaller - preference from the host, it enforces a 'minimum free disk space' - to keep from filling up the drive. Recommend setting this no - smaller than .001 (1MB or 1,000,000 bytes). Default is .001. -"); - -list_item("sched_disk_space_check_hardcoded", "Controls how the - above three settings are interpreted by the web page php scripts. - This setting is for projects that updated the php scripts to - get the default disk space usage settings from config.xml, but - haven't updated their scheduler to do the same. -"); - -list_item("max_claimed_credit", - "If a result claims more credit than this, mark it as invalid." -); -list_item("grant_claimed_credit", - "If set, grant the claimed credit, - regardless of what other results for this workunit claimed. - These is useful for projects where - different instances of the same job - can do much different amounts of work. - " -); -list_item("symstore", - "URL of your project's symbol store, - used for debugging Windows applications." -); -list_item("dont_delete_batches", - "If this boolean is set, - the file deleter won't delete any files for which - the corresponding workunit or result record has - a positive value of the the 'batch' field. - This lets you keep files on disk until you're done with them. - Create workunits with a positive batch number, - and zero out (or negate) the batch number when you're done - looking at the files - (you can do this with a SQL query). - If you use this option, replace the indices on - file_delete_state with indices on (file_delete_state, batch)." -); -list_item("sched_debug_level", - "Verbosity level for scheduler log output. - 1=minimal, 2=normal (default), 3=verbose." -); -list_item("fuh_debug_level", - "Verbosity level for file upload handler log output. - 1=minimal, 2=normal (default), 3=verbose." -); -list_item("verify_files_on_app_start", - "Before starting or restarting an app, - check contents of input files and app version files - by either MD5 or digital signature check. - Detects user tampering with file - (but doesn't really increase security, - since user could also change MD5s or signatures in - client state file)." -); - -list_end(); - -// THE INFORMATION BELOW NEEDS TO BE ORGANIZED AND PUT INTO TABLES OR SOME OTHER LESS CRAMPED FORM -echo " -Tasks are periodic, short-running jobs. -<cmd> and <period> are required. -OUTPUT specifies the file to output and by default is COMMAND_BASE_NAME.out. -Commands are run in the <bin_dir> directory -which is a path relative to <project_dir> and output to <log_dir>. - -

-Daemons are continuously-running programs. -The process ID is recorded in the <pid_dir> directory -and the process is sent a SIGHUP in a DISABLE operation. -

-Both tasks and daemons can run on a different host (specified by <host>). -The default is the project's main host, which is specified in config.host -A daemon or task can be turned off by adding the <disabled> element. -As well, there may be some tasks you wish to run via cron regardless of -whether or not the project is enabled (for example, a script that logs the -current CPU load of the host machine). You can do so by adding the -<always_run> element (<disabled> takes precedence over <always_run>). -"; page_tail(); ?> diff --git a/doc/contact.php b/doc/contact.php index 136795a16f..d5b32fbd1a 100644 --- a/doc/contact.php +++ b/doc/contact.php @@ -99,7 +99,7 @@ the BOINC software:

"; $i = 0; -$n = 3; +$n = 4; function show_name($x) { global $i; global $n; diff --git a/doc/create_project.php b/doc/create_project.php index af2b777593..adac2b4fd8 100644 --- a/doc/create_project.php +++ b/doc/create_project.php @@ -67,6 +67,11 @@ Creating a BOINC project

  • The BOINC database
  • Directory structure
  • The project configuration file +
  • Compile BOINC software
  • Groups and permissions @@ -92,7 +97,7 @@ Creating a BOINC project Getting work done +"; +echo " + "; page_tail(); ?> diff --git a/doc/server_components.php b/doc/server_components.php index 044b108870..024961f9bd 100644 --- a/doc/server_components.php +++ b/doc/server_components.php @@ -8,8 +8,11 @@ A BOINC project consists of the following components:

    diff --git a/doc/tool_start.php b/doc/tool_start.php index f7457d4113..38a0177fe4 100644 --- a/doc/tool_start.php +++ b/doc/tool_start.php @@ -2,74 +2,69 @@ require_once("docutil.php"); page_head("Project control"); echo " +

    Project control scripts

    + +The following Python scripts control a project: +"; +list_start(); +list_item("bin/start", + "Start the project: start all daemons, + and remove the stop_sched and stop_daemon files (see below)." +); +list_item("bin/stop", + "Stop the project (create the stop_sched and stop_daemon files)" +); +list_item("bin/start --cron", + "If the project is started, perform all periodic tasks that are past due, + and start any daemons that aren't running. + Otherwise do nothing." +); +list_item("bin/status", + "Show whether the project is stopped. + Show the status of all daemons. + Show the status of all periodic tasks + (e.g., when they were last executed)." +); +list_end(); +echo "

    Trigger files

    The following files (in the project root directory) can be used to turn off various parts of a project. -

    -   stop_sched
-
    -Have the scheduler return 'project down' messages. -
    -   stop_daemons
-
    -Tell all daemon process to exit. - -
    -   stop_web
-
    -Have the web site return 'project down' messages -for all functions that require database access. - -
    -   stop_upload
-
    -Have the file upload handler return transient error messages to clients -(they'll back off and retry later). - +"; +list_start(); +list_item("stop_sched", + "Have the scheduler return 'project down' messages." +); +list_item("stop_daemons", + "Tell all daemon process to exit." +); +list_item("stop_web", + "Have the web site return 'project down' messages + for all functions that require database access." +); +list_item("stop_upload", + "Have the file upload handler return transient error messages to clients + (they'll back off and retry later)." +); +list_end(); +echo "

    The presence of a file triggers the function. For example, to turn off data-driven web pages, type 

        touch stop_web
    -and to them back on, type +and to turn them back on, type 
        rm stop_web

    -If all three files are present, no database access will occur. +If the first three files are all present, no database access will occur. You should do this during most maintenance functions (such as upgrading software). - -

    Project control scripts

    - -The following Python scripts control a project: -
    -   bin/start
-
    -Start the project: start all daemons, -and remove the stop_sched and stop_daemon files. -
    -   bin/stop
-
    -Stop the project (create the stop_sched and stop_daemon files) -
    -   bin/start --cron
-
    -If the project is started, perform all periodic tasks that are past due, -and start any daemons that aren't running. -Otherwise do nothing. -
    -   bin/status
-
    -Show whether the project is stopped. -Show the status of all daemons. -Show the status of all periodic tasks -(e.g., when they were last executed). - "; + page_tail(); ?> - diff --git a/doc/trickle.php b/doc/trickle.php index 55b1574ccd..5403507c76 100644 --- a/doc/trickle.php +++ b/doc/trickle.php @@ -1,16 +1,25 @@ Trickle messages     let applications communicate with the server during the execution of a workunit. -They are intended for applications that have -long work units (multiple days). -Trickle messages may go in either direction: -'trickle up' messages go from application to server, -'trickle down' messages go from server to application. -Typical uses of this mechanism: +They are intended for applications that have long workunits (multiple days). + +

    +Trickle messages may from client to server or vice versa. +Messages are XML documents. + +

    Trickle-up messages

    +

    +Trickle-up messages go from application to server. +They are handled by trickle handler daemons running on the server. +Each message is tagged with a 'variety' (a character string). +Each daemon handles messages of a particular variety. +(This is used, typically, to distinguish different applications.) +Example uses:

    • The application sends a trickle-up message containing @@ -22,32 +31,33 @@ so that users can be granted incremental credit The application sends a trickle-up message containing a summary of the computational state, so that server logic can decide if the computation should be aborted. +
    + + +

    Trickle-down messages

    +

    + +Trickle-down messages go from server to application. +Each one is addressed to a particular host, +and must include an element <result_name> +identifying the result to which the message is addressed. +If that result is still running on the host, it is delivered to it. +Example uses: + +

      +
    • +The server sends a message telling the application to abort.
    • -The server sends a trickle-down message -telling the application to abort. - -
    • -The server sends a trickle-down message -containing the user's current total credit. +The server sends a message containing the user's current total credit.

    -Trickle messages are asynchronous and reliable. +Trickle messages are asynchronous, ordered, and reliable. Trickle messages are conveyed in scheduler RPC messages, so they may not be delivered immediately after being generated. - -

    -To handle trickle-down messages, a project must include the line -

    -<msg_to_host/>
-
    -in the configuration (config.xml) file. - - - "; page_tail(); diff --git a/doc/trickle_api.php b/doc/trickle_api.php index 0e42cd0447..413fb9ac50 100644 --- a/doc/trickle_api.php +++ b/doc/trickle_api.php @@ -3,36 +3,72 @@ require_once("docutil.php"); page_head("Trickle message API"); echo " -

    API (application)

    +The interface for trickle messages +includes both client-side and server-side components. +

    Client-side API

    +To send a trickle-up message, call 
     int boinc_send_trickle_up(char* variety, char* text)
    -sends a trickle message of the given variety. -Returns zero if success.

    +To receive a trickle-down message, call 

     int boinc_receive_trickle_down(char* buf, int len)
    -receives a trickle message. -Returns true (nonzero) if there was a message. -Messages are delivered in order. +This returns true (nonzero) if there was a message. -

    API (server)

    +

    Server-side API

    -To handle trickle messages, -use the daemon process 'trickle_handler'. -You must supply the following function: +

    +To handle trickle-up messages, use a 'trickle_handler' daemon. +This is a program, based on sched/trickle_handler.C, linked with a function ",html_text(" -int handle_trickle(TRICKLE_UP&); +int handle_trickle(MSG_FROM_HOST&); + +struct MSG_FROM_HOST { + int create_time; + int hostid; + char variety[256]; // project-defined; what kind of msg + char xml[MSG_FROM_HOST_BLOB_SIZE]; +}; + ")," -You may send trickle-down messages, from this function or elsewhere, -as follows: + +This function should return zero if the message was handled successfully; +otherwise it will be retried later. +The 'hostid' field identifies the host from which the message was sent. +The daemon must be passed a '-variety X' command-line argument, +telling it what kind of messages to handle. +The daemon should be specified in the +project configuration file. +

    +To send send trickle-down messages +(from a trickle handler daemon or other program) +you must insert a record in the 'msg_to_host' table. +From C/C++, this is done as follows: ",html_text(" -DB_TRICKLE_DOWN tdown; -// ... populate the tdown object -tdown.insert(); +DB_MSG_TO_HOST mth; + +mth.clear(); +mth.create_time = time(0); +mth.hostid = hostid; +sprintf(mth.xml, + \"\\n\" + \" %s\\n\" + \" ...\\n\" + \"\\n\", + ... +); +retval = mth.insert(); ")," +

    +To send trickle-down messages, a project must include the line +

    +<msg_to_host/>
+
    +in the configuration (config.xml) file. + "; page_tail(); diff --git a/doc/white.css b/doc/white.css index c28bccd1b7..789e968849 100644 --- a/doc/white.css +++ b/doc/white.css @@ -43,6 +43,10 @@ body { color: black; } +pre { + background-color: #d8e8ff; +} + th { background-color: #c8c8ff; color: black; diff --git a/html/inc/prefs.inc b/html/inc/prefs.inc index d13abfb75a..3bc9603917 100644 --- a/html/inc/prefs.inc +++ b/html/inc/prefs.inc @@ -55,7 +55,7 @@ define("IDLE_TIME_TO_RUN_DESC2", "
    (applies only if above is 'n define("START_END_DESC", "Do work only between the hours of"); define("START_END_DESC2", "
    (no restriction if equal)"); define("LEAVE_APPS_IN_MEMORY_DESC", - "Leave applications in memory while preempted? + "Leave applications in memory while suspended?
    (suspended applications will consume swap space if 'yes')"); define("CPU_SCHEDULING_DESC", "Switch between applications every
    (recommended: 60 minutes)"); diff --git a/sched/trickle_handler.C b/sched/trickle_handler.C index b4a5a5c6a7..c858738128 100644 --- a/sched/trickle_handler.C +++ b/sched/trickle_handler.C @@ -18,15 +18,15 @@ // 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA // -// trickle_handler - check and validate new trickle messages -// -app appname +// trickle_handler - process trickle-up messages +// -variety variety // [-d debug_level] // [-one_pass] // make one pass through table, then exit // [-asynch] // fork, run in separate process // // This program must be linked with an app-specific function: // -// int handle_trickle(TRICKLE_UP&) +// int handle_trickle(MSG_FROM_HOST&) // handle a trickle message // // return nonzero on error @@ -46,6 +46,9 @@ char variety[256]; extern int handle_trickle(MSG_FROM_HOST&); +// The following is an example; +// replace it with your own function +// int handle_trickle(MSG_FROM_HOST& mfh) { int retval;