v0.1.0 47aaa0f

0002-wayland-bindings-and-fd-ownership.md RawHistoryFolder

ADR 0002 — Wayland bindings and file-descriptor ownership

Status: accepted

Decision

WLTurbo owns the Wayland wire transport, object registry, XML scanner and the canonical generated bindings. NeferGUI consumes generated packages and never writes protocol code.

  • protocol/core is generated from wayland.xml. Only wl_display and wl_registry bootstrap code is handwritten.
  • Generated child objects keep their concrete type and typed event dispatch.
  • Required extensions and the behavior when a global is missing:
Binding Use Missing global
xdg-shell window lifecycle fatal capability error
linux-dmabuf v4 feedback format and device selection fatal capability error
linux-drm-syncobj v1 explicit synchronization fatal capability error
viewporter fractional buffer mapping fatal when fractional scale is active
fractional-scale v1 preferred scale integer-scale fallback
text-input v3 IME IME unavailable, keyboard input still works
core data-device clipboard clipboard unavailable

Excluded: presentation-time, data-control, X11, compositor-private blur.

File descriptors

  • A request that sends an FD transfers ownership only after a complete successful send.
  • A received message owns exactly the FDs declared by its signature. Socket reads are not message boundaries.
  • Missing or extra FDs, truncated ancillary data, malformed payloads and unknown signatures are protocol errors. FD 0 is valid.
  • Without a handler, owned FDs are closed. An owned FD reaches exactly one handler path.
  • Decode, dispatch, cancellation, object destruction and shutdown close every unclaimed FD.
source
1# ADR 0002 — Wayland bindings and file-descriptor ownership
2
3Status: accepted
4
5## Decision
6
7WLTurbo owns the Wayland wire transport, object registry, XML scanner and the canonical generated bindings. NeferGUI consumes generated packages and never writes protocol code.
8
9- `protocol/core` is generated from `wayland.xml`. Only `wl_display` and `wl_registry` bootstrap code is handwritten.
10- Generated child objects keep their concrete type and typed event dispatch.
11- Required extensions and the behavior when a global is missing:
12
13| Binding | Use | Missing global |
14|---|---|---|
15| xdg-shell | window lifecycle | fatal capability error |
16| linux-dmabuf v4 feedback | format and device selection | fatal capability error |
17| linux-drm-syncobj v1 | explicit synchronization | fatal capability error |
18| viewporter | fractional buffer mapping | fatal when fractional scale is active |
19| fractional-scale v1 | preferred scale | integer-scale fallback |
20| text-input v3 | IME | IME unavailable, keyboard input still works |
21| core data-device | clipboard | clipboard unavailable |
22
23Excluded: presentation-time, data-control, X11, compositor-private blur.
24
25## File descriptors
26
27- A request that sends an FD transfers ownership only after a complete successful send.
28- A received message owns exactly the FDs declared by its signature. Socket reads are not message boundaries.
29- Missing or extra FDs, truncated ancillary data, malformed payloads and unknown signatures are protocol errors. FD 0 is valid.
30- Without a handler, owned FDs are closed. An owned FD reaches exactly one handler path.
31- Decode, dispatch, cancellation, object destruction and shutdown close every unclaimed FD.

Keyboard shortcuts

Single-key shortcuts are on. ctrl k and esc work whatever this says.

ctrl k :
go to a section, branch, tag, file or repository
?
this list
j k
move the row cursor down / up
enter
open the row under the cursor; on Files, a directory opens or closes in place
↑ ↓ ← → home end
in the file tree (focus on a row): previous / next row, close / open a directory or go to its parent / first entry, first / last row. They never open a file
l h
on Files: open a directory or a file / close a directory or go up to its parent, then to the parent page. Elsewhere: into the side panel (on a merge request, its files) / back to the content; there j k move between its controls
g g G
first / last row
/
filter the list; on Files, find a file anywhere in the repository (esc clears, enter opens the best match)
b
switch branch or tag
g s g f g c g b g m g i g r g a
tabs: summary, files, commits, branches & tags, merge requests, issues, releases, actions (when available)
g h
home
w
wide mode: use the whole width of the screen, or not (remembered)
y
copy a permalink pinned to the commit
d u x
diff: split / unified / collapse or expand all
e E
diff: the whole file in view / every file, with the lines the hunks hide
n
merge request: next note in the diff
esc
close a dialog, leave a field

Branches 1

Tags 12

↑↓ moveenter openesc close