BrlAPI Reference manual: Concurrency management between BrlAPI clients

Next Previous Contents

## 3. Concurrency management between BrlAPI clients

An essential purpose of BrlAPI is to manage concurrent access to the braille display between the brltty daemon and applications. This concurrency is managed "per Tty". We first describe this with a flat view, and then consider Tty hierarchy.

## 3.1 VT switching

Let's first describe how things work with the simple case of a single series of Virtual Ttys (VTs), the linux console for instance.

As described in General Description, before being able to write output, a BrlAPI client has to "get" a tty, i.e. it sends to the BrlAPI server the number of the linux' Virtual Tty on which it is running. The BrlAPI server uses this information so as to know which client's output should be shown on the braille display, according to the focus teller's information.

Let's say some client A is running on VT 2. It "got" VT 2 and wrote some output on its BrlAPI connection. The focus teller is brltty here: it always tells to the BrlAPI server which VT is currently shown on the screen and gets usual keyboard presses (it is "active").

Let's say VT 1 is active, then the BrlAPI server shows brltty's output on the braille display. I.e. the usual brltty screen reading appears. Moreover, when braille keys are pressed, they are passed to brltty, so that usual screen reading can be performed. When the user switches to VT 2, brltty (as focus teller) tells it to the BrlAPI server, which then remembers that client A has got it and has produced some output. The server then displays this output on the braille display. Note that A doesn't need to re-submit its output: the server had recorded it so as to be able to show it as soon as the focus switches to VT 2. Whenever some key of the braille device is pressed, BrlAPI looks whether it is in the list of keys that client A said to be of his interest. If it is, it is passed to A (and not to brltty). If it isn't, it is passed to brltty (and not to A).

As a consequence, whenever clients get and release Ttys and the user switches between Ttys, either the brltty screen reading or the client's output is automatically shown according to rather natural rules.

## 3.2 A pile of "paper sheets"

Let's look at VT 2 by itself. What is shown on the braille display can be seen as the result of a pile of two paper sheets. brltty is represented by the bottom sheet on which its screen reading is written, and client A by the top sheet on which its output is written. A's sheet hence "covers" brltty's sheet: A's output "mask" brltty's screen reading.

A may yet want to temporarily let brltty's screen reading appear on VT 2, while still receiving some key presses, for instance. For this, it sends a "void" write. The server then clears the recorded output for this connection (in the sheet representation, the sheet becomes "transparent"). As a consequence, brltty's output is automatically shown (by transparency in the sheet representation), just like if A had released the Tty.

Keypresses are handled in a similar way: A's desire to get key presses is satisfied first before brltty.

Let's say some other client B (probably launched by A) also gets VT 2 and outputs some text on its BrlAPI connection. This adds a third sheet, on top of the two previous ones. It means that the BrlAPI server will show B's output on the braille device. If A then outputs some text, the server will record it (on A's sheet which hence becomes opaque again), but it won't be displayed on the braille device, since B's sheet is still at the top and opaque (i.e. with some text on it). But if B issues a void write, the server clears its ouput buffer (i.e. B's sheet becomes transparent), and as a result A's output appear on the braille display (by transparency through B's sheet).

The sheet order is by default determined by the Tty "get"ting order. Clients can however change their priority (which by default is 50) to a higher value in order to show up higher in the pile, or to a lower value in order to hide lower in the pile.

## 3.3 Hierarchy

Now, what happens when running some screen program on, say, VT 3? It emulates a series of Ttys, whose output actually appear on the same VT 3. That's where a hierarchy level appears: the focus information is not only the VT number but also, in the case of VT 3, which screen window is active. This hence forms a tree of Ttys: the "root" being the vga driver's output, whose sons are VTs, and VT 3 has the screen windows as sons. Brltty is a focus teller for the root, screen will have to be a focus teller for VT 3. Screen should then get VT 3, not display anything (so that the usual brltty screen reading will be shown by transparency), and tell the BrlAPI server which screen window is active (at startup and at each window switch). This is not implemented directly in screen yet, but this may be achieved via a second brltty daemon running the Screen driver (but it isn't yet able to get the current window number though) and the BrlAPI driver.

A BrlAPI client C running in some screen window number 1 would then have to get the Tty path "VT 3 then window 1", which is merely expressed as "3 1". The window number is available in the `WINDOW` environment variable, set by screen. The VT number, which actually represents the "path to screen's output" should be available in the `WINDOWPATH` environment variable, also set by screen. The client can thus merely concatenate the content of `WINDOWPATH` (which could hold many levels of window numbers) and of `WINDOW` and give the result as tty path to the BrlAPI server, which then knows precisely where the client's usual output resides. In practice, applications just need to call `brlapi_enterTtyMode(BRLAPI_TTY_DEFAULT)`, and the the BrlAPI client library will automatically perform all that.

Whenever the user switches to VT 3, the BrlAPI server remembers the window that screen told to be active. If it was window 1, it then displays C's output (if any). Else brltty's usual screen reading is shown. Of course, several clients may be run in window 1 as well, and the "sheet pile" mecanism applies: brltty's sheet first (at the root of the Ttys tree), then screen's sheet (which is transparent, on VT 3), then C's sheet (on window 1 of VT 3), then other clients' sheets (on the same window).

Ttys are hence organized in a tree, each client adding its sheet at some tty in the tree.

## 3.4 The X-window case

Let's say some X server is running on VT 7 of a Linux system. Xorg's xinit and xdm commands automatically set the X session's `WINDOWPATH` environment variable to "7", so that X11 BrlAPI clients started from the session just need to call brlapi_enterTtyMode(xid) where xid is the X-window ID of the window of the client. The BrlAPI library will automatically prepend the content of `WINDOWPATH` to it.

For text-based BrlAPI clients running in an xterm (which should just call `brlapi_enterTtyMode(BRLAPI_TTY_DEFAULT)` as explained in the previous section), BrlAPI detects the window id thanks to the `WINDOWID` variable set by xterm.

Screen readers are not bound to a particular window, so they should call brlapi_enterTtyModeWithPath(NULL, 0) to let the BrlAPI library only send the content of `WINDOWPATH`, expressing that screen readers take the whole tty. The user should notably launch xbrlapi, which is a focus teller for X-window as well as a keyboard simulator (brltty can't reliably simulate them at the kernel level in such situation). For accessing AT-SPI contents (like gnome or kde applications), Orca should also be launched. For accessing AT-SPI terminals (like gnome-terminal) in the same way as in the console, a second brltty daemon running the at-spi screen driver and the BrlAPI driver can also be launched. All three would get the VT of the X session, in that order (for now): xbrlapi first, then orca and brltty at last. When the X focus is on an AT-SPI terminal, brltty will hence be able to grab the braille display and key presses. Else orca would get them. And xbrlapi would finally get remaining key presses and simulate them.

Note: old versions of `xinit`, `xdm`, `kdm` or `gdm` do not automatically set the `WINDOWPATH` variable. The user can set it by hand in his `~/.xsession`, `~/.xinitrc`, `~/.gdmrc`... to "7"

Note: some Operating Systems like Solaris do not have VTs. In that case `WINDOWPATH` is empty or not even set. Everything explained above still work fine.

## 3.5 Detaching

Several programs allow detaching: screen and VNC for instance. In such situation, an intermediate BrlAPI server should be run for each such session. Clients would connect to it, and it would prepend the "current tty" path on the fly while forwarding things to the root BrlAPI server. This intermediate server is yet to be written (but it is actually relatively close to be).

Next Previous Contents