= 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 resource usage settings vary as a function of external factors.

Note: the motivation for this is discussed [PrefsRemodel 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 settings ==

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

"Dynamic" settings 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 [type][device]:: don't run GPU jobs.  Optional GPU type (nvidia, amd, intel) and device #.
 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" settings 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 setting groups:
{{{
<settings>
   [ <max_ncpus_pct>x</max_ncpus_pct> ]
   ...
</settings>

<static_settings>
   [ <disk_max_used_gb>x</disk_max_used_gb> ]
   ...
</static_settings>
}}}

All elements are optional;
a group can define some elements but not others.
If A and B are setting groups, 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 dynamic setting group.
XML format:
{{{
<clause>
   <condition> ... </condition>
   <settings> ... </settings>
<clause>
}}}

== Preference sets ==

A "preference set" is a list of clauses.
XML format:
{{{
<computing_prefs>
   <clause> ... </clause>
   ...
   <static_settings> ... <static_settings>
</computing_prefs>
}}}

The semantics are as follows.
X is a dynamic setting group, 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 settings.
At the conclusion, X is the dynamic settings 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>
      <settings>
         <max_ncpus_pct>50</max_ncpus_pct>
         <ram_max_used_frac>.5</ram_max_used_frac>
      </settings>
   </clause>
   <clause>
      <condition>
         <term>
            <type>greater_than</type>
            <item>idle_time</time>
            <value>180</value>
         </term>
      </condition>
      <settings>
         <max_ncpus_pct>100</max_ncpus_pct>
         <ram_max_used_frac>.9</ram_max_used_frac>
      </settings>
   </clause>
</computing_prefs>
}}}