gizlang/client
A Wayland client over a Unix socket: the requests and events a window needs (the registry, a surface with a shared memory buffer, an xdg toplevel, the seat's pointer and keyboard). A message is a header of the object id and of its size and opcode, then its arguments in 32-bit words. A file descriptor travels beside the bytes, as ancillary data. The system calls are raw, and their numbers come from gizlang/linux for the ABI of this machine, so the same program runs on GizOS and on Linux, on each CPU that machine_syscall serves.
import * as Client from "gizlang/client";Types
Calls
type Calls = { socket: i64; connect: i64; sendmsg: i64; recvmsg: i64; close: i64; memfd: i64; ftruncate: i64; mmap: i64; }The wire numbers of the calls this client makes, on the ABI of this machine.
socket:i64connect:i64sendmsg:i64recvmsg:i64close:i64memfd:i64ftruncate:i64mmap:i64
Event
type Event = { object: i64; opcode: i64; at: i64; size: i64; }An event of an object: its id, its opcode, and the address and size of its arguments (after the header). The arguments stay valid until consume() takes the event off the input.
object:i64opcode:i64at:i64size:i64
Global
type Global = { id: i64; interfaceName: string; version: i64; }A global of the registry: its name, its interface and its version.
id:i64interfaceName:stringversion:i64
Client
type Client = { fd: i64; out: i64; outUsed: i64; input: i64; inputUsed: i64; nextId: i64; scratch: i64; calls: Calls; fds: Vec<i64>; }A connection: the socket, the outgoing and incoming buffers, the next object id, the scratch of the message headers and the calls of this machine. The memory stays mapped for the connection's life.
fd:i64out:i64outUsed:i64input:i64inputUsed:i64nextId:i64scratch:i64calls:gizlang_wayland.Callsfds:Vec<i64>— The descriptors that came with events (a keymap's, a selection's pipe), oldest first, until takeFd.
Functions
calls
function calls(): CallsThe calls of this machine, each number looked up once in the ABI that machine_syscall calls with. A call the ABI lacks is -1, and connect() throws ENOSYS for it.
Effects: fail.
memory
function memory(wire: Calls, count: i64): i64 throws i64COUNT zeroed bytes of private memory, page-aligned; the process keeps them for its life. A failure throws its errno.
Effects: fail, read, write.
connect
function connect(path: string): Client throws i64A client connected to the compositor socket at PATH.
Effects: fail, read, write.
adopt
function adopt(fd: i64): Client throws i64A client on FD, the end of a connected socket the compositor gave the program in WAYLAND_SOCKET.
Effects: fail, read, write.
close
function close(wire: Calls, fd: i64): voidClose descriptor FD (a shared memory file once the compositor has it).
Effects: read, write.
newId
function newId(c: mut Client): i64A new object id, for the object a request creates.
Effects: fail.
begin
function begin(c: mut Client, object: i64, opcode: i64): i64Start a message to OBJECT with OPCODE. Its arguments follow with the put functions, then end() closes it.
Effects: fail, write.
putNumber
function putNumber(c: mut Client, value: i64): voidA 32-bit number: an unsigned id, a count, or a fixed-point value (24.8) as its 256ths.
Effects: fail, write.
putText
function putText(c: mut Client, value: string): voidA string: its length with the NUL, its bytes, the NUL, then the padding to 32 bits.
Effects: fail, write.
end
function end(c: mut Client, at: i64): voidClose the message that began at AT: its size goes into the header. It is sent by flush().
Effects: fail, read, write.
flush
function flush(c: mut Client, fd: i64): void throws i64Send the closed messages. FD, when not 0, travels with the first of them as ancillary data; the caller closes it.
Effects: fail, read, write.
next
function next(c: mut Client): Event throws i64The next event, reading the socket when no whole message is buffered. Take it off with consume() before the next call. A read that fails throws its errno.
Effects: fail, read, write, alloc.
consume
function consume(c: mut Client, event: Event): voidTake EVENT off the input once it is handled.
Effects: fail, read, write.
takeFd
function takeFd(c: mut Client): i64The descriptor of the event being read that carries one (wl_keyboard.keymap, wl_data_source.send): the oldest that came; -1 when none did. Its taker closes it.
Effects: fail, alloc.
argUnsigned
function argUnsigned(event: Event, offset: i64): i64The 32-bit unsigned argument at OFFSET bytes into the event's arguments.
Effects: fail, read.
argSigned
function argSigned(event: Event, offset: i64): i64The 32-bit signed argument at OFFSET bytes into the event's arguments.
Effects: fail, read.
argText
function argText(event: Event, offset: i64): stringThe string argument at OFFSET bytes, without its NUL.
Effects: fail, read, alloc.
textBytes
function textBytes(length: i64): i64The bytes a string argument takes, from its length word (with the NUL) to the padding.
Effects: fail.
global
function global(event: Event): GlobalThe global of a wl_registry.global event.
Effects: fail, read, alloc.
sharedMemory
function sharedMemory(wire: Calls, count: i64): { fd: i64; at: i64; } throws i64A shared memory file of COUNT bytes, mapped read and write: its descriptor and its address. A failure throws its errno. The descriptor is for the compositor (create_pool), which then owns the memory with the client.
Effects: fail, read, write.
Constants
DISPLAY
const DISPLAY: i64 = 1The object id of wl_display, the first object of every connection.