Documents/README.Polling

~~~~~~~
Polling
~~~~~~~

.. include:: prologue.rst

As of release 5.0, BRLTTY has been converted from being polling-based to being 
event-based. This means, among other things, that it's now able to become 
completely idle whenever it doesn't have anything useful to do. For comparison, 
it formerly used a huge, central, main loop which was run frequently (about 25 
times per second), and which was aware of, and had to check for, every single
task that might need to be performed.

In practical terms, this change, when compared with how BRLTTY used to work, 
delivers at least the following significant benefits:

*  Noticeably improved response time. Near instant reaction to significant user
   and system events rather than waiting for the next polling cycle to check
   for them.

*  Much less system load. Just a few, short-lived bursts of activity when
   actually necessary rather than frequent, much longer-lived checking that,
   far more often than not, resulted in nothing needing to be done.

*  Way less battery drain. The system is no longer forced either to remain
   awake or to continually wake up after a rather brief nap.

There are cases in which polling is still being used. Some of these will
eventually be resolved by future code changes, while others, unfortunately, are
required due to host platform limitations.

.. topic:: Monitoring for Screen Updates

   This task involves checking for size changes, content changes, highlighting
   changes, cursor movement, etc. It's event-based on:

   *  Android

   *  Linux text consoles if the kernel is at least 2.6.37 (released on January 4,
      2011)

   *  Linux graphics consoles monitored via AT-SPI2.

   On other platforms, |frequent polling| is used.

.. topic:: Monitoring for Serial Input

   This task is event-based on:

   *  Linux

   On other platforms, |frequent polling| is used.

.. topic:: Monitoring for USB Input

   This task is event-based on:

   *  Linux

   On other platforms, |frequent polling| is used.

.. topic:: Monitoring for Bluetooth Input

   Tghis task is event-based on:

   *  Android

   *  Linux

   On other platforms, |frequent polling| is used.

.. topic:: Starting the Braille Driver

   On all platforms, |periodic retrying| is used.

.. topic:: Starting the Speech Driver

   On all platforms, |periodic retrying| is used.

.. topic:: Starting the Screen Driver

   On all platforms, |periodic retrying| is used.

.. topic:: Starting the Keyboard Monitor

   On all platforms, |periodic retrying| is used.

.. topic:: Creating the PID File

   On all platforms, |periodic retrying| is used.

.. |frequent polling| replace:: frequent polling (about every 40 milliseconds)
.. |periodic retrying| replace:: periodic retrying (about every five seconds)