GizStack
View .mdOpen in ChatGPTOpen in Claude

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.

gizlang
import * as Client from "gizlang/client";

Types

Calls

gizlang
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: i64
  • connect: i64
  • sendmsg: i64
  • recvmsg: i64
  • close: i64
  • memfd: i64
  • ftruncate: i64
  • mmap: i64

Event

gizlang
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: i64
  • opcode: i64
  • at: i64
  • size: i64

Global

gizlang
type Global = { id: i64; interfaceName: string; version: i64; }

A global of the registry: its name, its interface and its version.

  • id: i64
  • interfaceName: string
  • version: i64

Client

gizlang
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: i64
  • out: i64
  • outUsed: i64
  • input: i64
  • inputUsed: i64
  • nextId: i64
  • scratch: i64
  • calls: gizlang_wayland.Calls
  • fds: Vec<i64> — The descriptors that came with events (a keymap's, a selection's pipe), oldest first, until takeFd.

Functions

calls

gizlang
function calls(): Calls

The 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

gizlang
function memory(wire: Calls, count: i64): i64 throws i64

COUNT zeroed bytes of private memory, page-aligned; the process keeps them for its life. A failure throws its errno.

Effects: fail, read, write.

connect

gizlang
function connect(path: string): Client throws i64

A client connected to the compositor socket at PATH.

Effects: fail, read, write.

adopt

gizlang
function adopt(fd: i64): Client throws i64

A client on FD, the end of a connected socket the compositor gave the program in WAYLAND_SOCKET.

Effects: fail, read, write.

close

gizlang
function close(wire: Calls, fd: i64): void

Close descriptor FD (a shared memory file once the compositor has it).

Effects: read, write.

newId

gizlang
function newId(c: mut Client): i64

A new object id, for the object a request creates.

Effects: fail.

begin

gizlang
function begin(c: mut Client, object: i64, opcode: i64): i64

Start a message to OBJECT with OPCODE. Its arguments follow with the put functions, then end() closes it.

Effects: fail, write.

putNumber

gizlang
function putNumber(c: mut Client, value: i64): void

A 32-bit number: an unsigned id, a count, or a fixed-point value (24.8) as its 256ths.

Effects: fail, write.

putText

gizlang
function putText(c: mut Client, value: string): void

A string: its length with the NUL, its bytes, the NUL, then the padding to 32 bits.

Effects: fail, write.

end

gizlang
function end(c: mut Client, at: i64): void

Close the message that began at AT: its size goes into the header. It is sent by flush().

Effects: fail, read, write.

flush

gizlang
function flush(c: mut Client, fd: i64): void throws i64

Send 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

gizlang
function next(c: mut Client): Event throws i64

The 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

gizlang
function consume(c: mut Client, event: Event): void

Take EVENT off the input once it is handled.

Effects: fail, read, write.

takeFd

gizlang
function takeFd(c: mut Client): i64

The 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

gizlang
function argUnsigned(event: Event, offset: i64): i64

The 32-bit unsigned argument at OFFSET bytes into the event's arguments.

Effects: fail, read.

argSigned

gizlang
function argSigned(event: Event, offset: i64): i64

The 32-bit signed argument at OFFSET bytes into the event's arguments.

Effects: fail, read.

argText

gizlang
function argText(event: Event, offset: i64): string

The string argument at OFFSET bytes, without its NUL.

Effects: fail, read, alloc.

textBytes

gizlang
function textBytes(length: i64): i64

The bytes a string argument takes, from its length word (with the NUL) to the padding.

Effects: fail.

global

gizlang
function global(event: Event): Global

The global of a wl_registry.global event.

Effects: fail, read, alloc.

sharedMemory

gizlang
function sharedMemory(wire: Calls, count: i64): { fd: i64; at: i64; } throws i64

A 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

gizlang
const DISPLAY: i64 = 1

The object id of wl_display, the first object of every connection.