Overview

Process & Thread priority can be modified under BRAHMS. The Execution Parameter Priority is the key value, and can be set to Low, Normal, High or Realtime. Usually, Low or High will be an appropriate choice, see the Execution Parameter itself for more information.

Warnings
  • Incautious usage of Priority can cause you to lose data or worse - please read the Discussion, below, before changing the Priority setting.

Details

Windows

On Windows, Priority is used to select between IDLE, NORMAL, HIGH and REALTIME process priority classes. Individual threads are set to LOW, BELOWNORMAL, NORMAL, ABOVENORMAL, and HIGH thread priority classes, respectively as RECEIVER, DELIVERER, WORKER, SENDER, CALLER. Important features of this arrangement are as follows.

  1. Within a voice, the CALLER thread, which includes the monitoring functions (including the Cancel button), always has the highest priority so that it is the most responsive thread.
  2. Within a voice, the remaining threads are prioritised such that local queues tend to be kept empty rather than tend to be filling up.
  3. Relative to other user processes running on the system, all BRAHMS threads are either lower (at Low) or higher (at High or Realtime) priority.

NIX

On NIX, Priority values of Low to High are used to select between 10, 0 and -10 nice values for the process, whilst individual threads are scheduled at the same priority by SCHED_OTHER. A Priority value of Realtime, however, causes all threads to be scheduled according to SCHED_FIFO (or SCHED_RR, tbc), and be entered into scheduling queues above the SCHED_OTHER queue. In this case, individual threads are ordered into queues 1, 2, 3 to N, N+1 and N+2, for RECEIVER, DELIVERER, WORKER, SENDER and CALLER, respectively. Thus, WORKER threads are spread amongst (N-2) queues. At time of writing, N=3, so the CALLER thread is in queue 5. Important features of this arrangement are as follows.

  1. When using Realtime, within a voice, the CALLER thread, which includes the monitoring functions (including the Cancel button), always has the highest priority so that it is the most responsive thread. When not using Realtime, this is not true.
  2. When using Realtime, within a voice, the remaining threads are prioritised such that local queues tend to be kept empty rather than tend to be filling up. When not using Realtime, this is not true.
  3. Relative to other user processes running on the system, all BRAHMS threads are either lower (at Low) or higher (at High or Realtime) priority.

Discussion

Implementation is not identical on Windows and NIX. However, the main feature for everyday use is item 3 in each list, above, allowing the user to control whether BRAHMS runs as background processing, or as priority processing (by setting Priority to either Low or High). Setting Priority to Normal is not particularly meaningful, and may not be a useful thing to do.

In addition, the Realtime setting provides "best effort" behaviour on all platforms for systems that interact with hardware. BRAHMS threads will be prioritised over and above most other threads on the system (roughly, all non-kernel processing). Provided that the system is arranged such that kernel processing is kept to a minimum, this may be sufficient to meet hard real-time processing constraints with high probability. However, this does not provide the same level of real-time support as would using a real-time operating system.

Note that this means that the Realtime setting of Priority should be used with caution. It is intended for use for closed-loop systems that interact with any hardware clock (e.g. a hardware controller), such that all BRAHMS threads are forced to wait at least occasionally whilst data is exchanged with hardware. In this case, the system as a whole will remain responsive. If you execute a pure software system at Realtime Priority, there is a danger that your machine will freeze for the duration of the execution. Under some conditions, it may not recover from this freeze and you may lose data, or control of your hardware.

In summary, Realtime Priority may be indispensable when you are deploying a real-time controller, but it is entirely useless and will usually be counterproductive during under other conditions. Under typical conditions, it will not make processing run any faster than using High Priority.

What can go wrong

Windows

Usually nothing, because there are no security barriers in place in a default Windows installation. If your system has security preventing you from raising priority above some level, you may see E_PRIORITY_FAIL if you try to set priority above that level. But I've never seen it.

However, if you try to use Priority Realtime, you may find only High reported in Task Manager. I don't know what might cause this silently to not work, though one web page I looked at suggested it might be because Hardware Virtualization is enabled in the BIOS (so, try disabling it). If this condition is present, you should find that you are unable to set the priority of any process in Task Manager to realtime, manually, and that you get an appropriate warning message in this case.

Linux

On Linux (and, presumably, OSX), users are prevented from raising priority beyond some limit by default. Usually, if you set Priority to High or above, you will generate E_PRIORITY_FAIL on Linux (annotated by the OS error code EACCES). The way to relieve this error is different for the "nice" priorities Low, Medium and High, versus the real-time priority Realtime.

For "nice" priority levels (Low, Normal, High), setting RLIMIT_NICE to a sufficiently low (high priority) value (at time of writing, -10) should fix this error. You can do this by making an entry in /etc/security/limits.conf, which might take the following form.

<user> - nice -10

For Realtime priority, raising RLIMIT_RTPRIO to a sufficiently high value (at time of writing, 5) should fix this error. The line in /etc/security/limits.conf should read something like this:

<user> - rtprio 5
Notes
  • You can replace <user> with * to make the setting affect all users.
Warnings
  • There may be security concerns if you make changes to system configuration files. If you are concerned, look into this more before you make any changes (or avoid using the higher priority levels).

X Windows

Under X, and similar client/server window managers, the thread responsible for updating the display of the GUI is not the same as the thread responsible for specifying those updates. The former runs, on my Ubuntu system today, in a process called "Xorg". The latter is the CALLER thread in BRAHMS. Thus, if you use Realtime Priority, you will find that, though the CALLER thread is sending GUI updates, the Xorg thread is not processing them (since the Xorg thread will be running under SCHED_OTHER). Thus, the GUI will not update unless there are wait states enforced in BRAHMS processing by interaction with a hardware clock. Another illustration of why it is bad to use Realtime Priority to run a pure software system; as the GUI fails to repaint, this is showing you that the system as a whole is freezing up because BRAHMS is taking all the compute time.