Computing preferences, version 2

This document describes a new system for "computing preferences" in BOINC. This system lets users express, as a set of logical rules, how dynamic parameters of resource usage vary as a function of external factors.

Note: the motivation for this is discussed here; that document is otherwise deprecated.

The goals of this system include:

• Generality: allow the expression of any preferences.
• Extensibility: make it possible to add new external factors (such as the current cost of electricity) without modifying the client.

Static and dynamic parameters

Various parameters control and limit BOINC's use of computing, memory, storage, and network communication.

"Dynamic" parameters can change in response to factors external to BOINC (such as time of day, non-BOINC CPU usage, etc.). These include:

cpu_usage_limit

CPU throttling fraction (0..1)

dont_use_cpu

don't run any jobs

dont_use_gpu

don't run GPU jobs

dont_do_file_xfer

don't do file xfers

dont_use_network

don't do any network communication at all

max_bytes_sec_down

max download data rate

max_bytes_sec_up

max upload data rate

max_ncpus

max # of CPUs to use

max_ncpus_pct

max % of CPUs to use

ram_max_used_frac

max fraction of RAM to use

"Static" parameters don't vary over time. These include:

confirm_before_connecting

ask before creating network connection

cpu_scheduling_period

time between rescheduling jobs

disk_max_used_gb

max disk usage

disk_max_used_pct

max % of disk to use

disk_min_free_gb

min free disk space

dont_verify_images

don't verify image files

hangup_if_dialed

hang up modem connection when done

leave_apps_in_memory

suspend (rather than quit) non-running jobs

work_buf_additional_days

when request work, ask for this much beyond min

work_buf_min_days

keep at least this much work

The XML representation of parameters:

<static_params>
   [ <disk_max_used_gb>x</disk_max_used_gb> ]
   ...
</static_params>

<dynamic_params>
   [ <max_ncpus_pct>x</max_ncpus_pct> ]
   ...
</dynamic_params>

All elements are optional; a parameter set can define some elements but not others. If A and B are parameter sets, the "overlay of A on B" is defined as A together with any elements in B that are not defined in A.

Prefs dictionary

External factors are stored in a "prefs dictionary", which is a name -> value map. The following entries are maintained by the BOINC client:

idle_time

# seconds since last user input

time

time of day

on_batteries

system is running on batteries

app_name

whether a given application is running

non_boinc_cpu_usage

fraction of CPU used for non-BOINC apps recently

daily_xfer_mb_N

number of MB of file transfer in last N days

on_ac_power

system is running on AC power (Android)

on_usb_power

system is running on USB power (Android)

wifi_online

WiFi network connection exists (Android)

user_active

system thinks user is active (Android)

battery_charge

battery charge level, 0..100 (Android)

battery_temperature

battery temperature, Centigrade (Android)

In addition, external programs can add items to the dictionary, and update their values, via GUI RPCs. Hence the prefs system is extensible without modifying the client.

Values are doubles; Booleans are encoded as 0/1.

Preference terms

Preferences are expressed in terms of "conditions" that are the conjunction of a set of "terms".

Each term is an assertion about a dictionary item. There are three types of assertions:

• "greater than": the value of the item is greater than a number X.
• "nonzero": the value of the item is nonzero (i.e. Boolean true)
• "time range": the value of the item (usually "time") lies in a set of day/week intervals.
• "app_running": an app of the given name is running

A term can also have a "not" flag, which if set reverses its sense.

The XML representation of a term:

<term>
   <item>item-name</item>
   <type>x</type>                  // greater_than, nonzero, time_range, app_running
   [<thresh>x</thresh>]            // if greater than
   [<time_range>...</time_range>]  // if time range
</term>

The representation of a time range:

<time_range>
   <start>x</start>
   <end>y</end>
   [
   <day_of_week>
      <day>x</day>                 // 0 .. 6
      <start>x</start>
      <end>y</end>
   </day_of_week>
   ... other days of week
   ]
</time_range>

x and y are hours (0..24). The first start/end apply to all days. This is overwritten by day_of_week elements.

Conditions

A "condition" is the conjunction ("and") of a set of terms, possibly negated. XML format:

<condition>
   [<not/>]
   <term> ... </term>
   ...
</condition>

The conjunction of an empty set of terms is true.

Clauses

A "clause" is the combination of a condition and a set of dynamic parameters. XML format:

<clause>
   <condition> ... </condition>
   <dynamic_params> ... </dynamic_params>
<clause>

Preference sets

A "preference set" is a list of clauses. XML format:

<computing_prefs>
   <clause> ... </clause>
   ...
   <static_params> ... <static_params>
</computing_prefs>

The semantics are as follows. X is a set of dynamic parameters, initially empty. The clauses are processed in order. For each clause C, evaluate its condition. If the condition is true, overlay X with C's dynamic parameters. At the conclusion, X is the dynamic parameters to be enforced by the client.

Example

The following says to use all the CPUs and 90% of the RAM if there has been no user input in 3 minutes, and to use 50% of the CPUs and 50% of the RAM otherwise:

<computing_prefs>
   <clause>
      <dynamic_params>
         <max_ncpus_pct>50</max_ncpus_pct>
         <ram_max_used_frac>.5</ram_max_used_frac>
      </dynamic_params>
   </clause>
   <clause>
      <condition>
         <term>
            <type>greater_than</type>
            <item>idle_time</time>
            <value>180</value>
         </term>
      </condition>
      <dynamic_params>
         <max_ncpus_pct>100</max_ncpus_pct>
         <ram_max_used_frac>.9</ram_max_used_frac>
      </dynamic_params>
   </clause>
</computing_prefs>