= Computing preferences, version 2 =

== Static and dynamic parameters ==

"Dynamic" parameters limit BOINC activity
and change in response to various factors.
Examples include limits on #CPUs, RAM usage, network usage, etc.

== Prefs dictionary ==

The "prefs dictionary" is a name -> value map,
containing values that can affect dynamic prefs.
Examples:

 * "idle_time": # seconds since last user input
 * "time": time of day
 * "on_batteries": whether system is running on batteries
 * "exclusive_app_running": whether an exclusive app is running
 * "non_boinc_cpu_usage": fraction of CPU used for non-BOINC apps recently

These values are updated by the client.

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 terms:

 * "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 (a time value) lies in a set of day/week intervals.

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

The XML representation of a term is
{{{
<term>
   <item>item-name</item>
   <type>x</type>     // 0 = greater than, 1 = nonzero, 2 = time range
   [<negate/>]
   [<thresh>x</thresh>]         // if greater than
   [time range]                 // if time range
</term>
}}}
and the representation of a time range is
{{{
<time_range>
   <start_hour>x</start_hour>
   <end_hour>y</end_hour>
   [
   <day>
      <day_of_week>x</day_of_week>
      <start_hour>x</start_hour>
      <end_hour>y</end_hour>
   <day>
</time_range>
}}}

== Conditions ==

A "condition" is the conjunction ("and") of a set of terms, possibly negated.
XML format:
{{{
<condition>
   [<negate/>]
   <term> ... </term>
   ...
</condition>
}}}

== 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>
   ...
</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, we evaluate its condition.
If the condition is true, we overwrite X with C's dynamic parameters.
At the conclusion, X is the dynamic parameters to be enforced by the client.