src/drafts/screen_internal

   1 I. Disclaimer
   2
   3 This document includes some of my personal understanding about the internal
   4 structure of GNU Screen. It's written to serve as a remainder to myself. I
   5 hope that it can help those not familiar with GNU Screen already. But be aware
   6 of any possible mistake in this document.
   7
   8
   9 II. Architecture
  10
  11 GNU Screen works in a client-server way. The two participants are called
  12 front-end and back-end respectively, sharing the same code base. When an
  13 instance of Screen launches, the command line arguments determines the role
  14 and the corresponding action.
  15
  16 Front-end send requests to back-end through a named-pipe or socket. And the
  17 back-end gives feed back by signal. The requests include attach, detach,
  18 resize, window create and command execution. The front-end does nothing more
  19 than send requests and act upon responses. When there are no such events, it
  20 simply sleeps to kill it's boring time. All other works are handled by the
  21 back-end.
  22
  23
  24 III. Important objects
  25
  26 There are several kinds of objects in Screen. Here are some of them.
  27
  28 A. Display
  29
  30 A Display stands for an attached display area. It corresponds to the real user
  31 tty that the attaching front-end runs in. Since there can be multiple users
  32 (or multiple attach from the same user), the possibly multiple displays are
  33 chained together in a single linked-list 'displays'. An Display object
  34 contains many global statuses and flags (terminal modes & flags etc.), also
  35 includes some events such as tty read & write.
  36
  37 B. Canvas, Viewport & Layout
  38
  39 Canvas is a place to draw contents on. They logically belong to a specific
  40 display.  However, a display can be further divided to several sub-regions,
  41 using the split command. As a result, the regions need corresponding canvases.
  42 Moreover, the way that a display is organised can be saved by Layout object.
  43 All Layout objects are linked together as a list. The active layout used by
  44 Display is stored with it. The canvas in a display that has input focus is
  45 called forecv.
  46
  47 To track the Canvases in a Display, Screen uses a two-dimensional link list.
  48 One list link (slnext & slprev) together all adjacent Canvases that are
  49 spitted in the same direction. The other is the stacking direction, or the
  50 Z-axis in 3D graphics. All such adjacent Canvases shares one container Canvas,
  51 which is inserted when a split with different direction is about to happen.
  52 Each Canvas points to it's container using slback and a container points to
  53 one of its random child using slprep. This structure actually link the
  54 Canvases together as a tree, which is very helpful when doing free and resize.
  55
  56 Finally, to ease the clipping when drawing in the canvas, there is also a
  57 viewport object to track the boundary of each canvas. (But why not the canvas
  58 itself?)
  59
  60 C. Window & Layer
  61
  62 Each Window in screen stands for a pseudo-terminal (or telnet connection,
  63 depending on the type of window) that runs inside screen. All relevant
  64 statuses and events are stored in this object. Many Windows can be shown in
  65 Display at once, the one that has input focus is called the fore Window.
  66
  67 To be shown in Canvases, a Window needs a object called Layer. A Layer can be
  68 drawn on multiple Canvases, either in one Display or in different Displays. So
  69 it also make sense to call it 'view'. However, the name Layer tells us that
  70 it's stackable. One can add an overlay to the existing one, such as the help
  71 page. Each Layer contains an operation function structure, providing important
  72 operation to process the input, draw line, clear, redraw, resize, abort and
  73 restore etc.
  74
  75 E users & ACL
  76
  77 TODO
  78
  79 IV. Event dispatching.
  80
  81 Screen uses asynchronous IO to handle all inputs/outputs in all ttys. Such
  82 asynchronous events, IO related or not, are organized as events, registered to
  83 a central event list and got scheduled by a scheduler.
  84
  85 The scheduler loops indefinitely. In each turn, it waits for some events to go
  86 ready using the Select() system call. There are three types of events,
  87 READ/WRITE, TIMEOUT and ALWAYS. The READ/WRITE events are mostly used to carry
  88 data between outer tty and ptys within screen. And the TIMEOUT events are
  89 mostly used to do periodically update. Different from other kinds of events,
  90 the TIMEOUT event is one-off, and should be re-scheduled if periodic
  91 activation is desired. Note that the TIMEOUT event has lower priority than
  92 READ/WRITE events, and the timeout specified is never adjusted to compensate
  93 the elapsed time. As a result, the period of activation should typically
  94 longer then specified.
  95