Computing preferences, version 2

Static and dynamic parameters

Various parameters control and limit BOINC's use of computing, memory, storage, and network communication. "Static" parameters don't vary over time; for example storage-related parameters are static. "Dynamic" parameters can change in response to factors external to BOINC (such as time of day, non-BOINC CPU usage, etc.). Dynamic parameters include limits on #CPUs, RAM usage, and network throughput.

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

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.

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. 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 periodically by the client. 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.

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

The XML representation of a term:

<term>
   <item>item-name</item>
   <type>x</type>                  // 1 = greater than, 2 = nonzero, 3 = time range
   [<negate/>]
   [<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>
</time_range>

Conditions

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

<condition>
   [<negate/>]
   <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>
   [ <static_params> ... </static_params> ]
   <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 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>
      <condition></condition>
      <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>gt</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>