Software: Apache/2.2.3 (CentOS). PHP/5.1.6 

uname -a: Linux mx-ll-110-164-51-230.static.3bb.co.th 2.6.18-194.el5PAE #1 SMP Fri Apr 2 15:37:44
EDT 2010 i686 

uid=48(apache) gid=48(apache) groups=48(apache) 

Safe-mode: OFF (not secure)

/usr/share/doc/brlapi-0.4.1/BrlAPI-HTML/   drwxr-xr-x
Free 50.94 GB of 127.8 GB (39.86%)
                            Encoder    Tools    Proc.    FTP brute    Sec.    SQL    PHP-code    Update    Feedback    Self remove    Logout    

Viewing file:     BrlAPI-3.html (9.77 KB)      -rw-r--r--

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 seenas the result of a pile of two paper sheets. brltty is represented by thebottom sheet on which its screen reading is written, and client A by thetop 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 determined by the Tty "get"ting order. Some mecanism will be added in near future for clients to precise "at which level its sheet should be inserted" so as to avoid race conditions on the "get"ting order.

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 WINDOWSPATH environment variable, also set by screen. The client can thus merely concatenates the content of WINDOWSPATH (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.

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. The user should also 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), gnopernicus should also be launched. For accessing AT-SPI terminals (like gnome-terminal), a second brltty daemon running the at-spi screen driver and the BrlAPI driver should also be launched. All three would get VT 7, in that order (for now): xbrlapi first, then gnopernicus 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 gnopernicus would get them. And xbrlapi would finally get remaining key presses and simulate them.

The user should also set in his ~/.xsession, ~/.xinitrc, ~/.gdmrc... the WINDOWSPATH environment variable to "7", so that clients running in xterms will be able to prepend it to the content of the WINDOWID variable (set by xterms) and give this Tty path to the BrlAPI server. Any screen run in some xterm should then concatenate these WINDOWSPATH and WINDOWID variables to form a new WINDOWSPATH variable to give to sessions running in it.

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).