~shunter/wayflan

5b27375882ec9d8d551663292ab9ec21138ab3ce — Samuel Hunter 1 year, 8 months ago 0d7c532
Clarify single-threadedness and server/compositor terminology

This commit clarifies in the README that the library is single-threaded
as it stands right now, but intends to be multi-threadable in the coming
future.

It also clarifies between Wayland servers and compositors, the former
often being casually called the latter since the wl_compositor is the
most critical/visible resource to most users.
M README.md => README.md +9 -9
@@ 8,8 8,7 @@ Wayflan is a from-scratch Wayland communication library for Common Lisp. It is
not a binding or a wrapper around
[libwayland](https://wayland.freedesktop.org/), but a re-implementation of the
Wayland protocol. This unties Lisp applications from per-proxy manual memory
allocation, toplevel-only C callbacks, and enables a closer interface with CLOS
and CLCS.
allocation, toplevel-only C callbacks, and enables a closer interface with lisp.

Wayflan makes a good-faith effort to mimic libwayland behavior not defined in
the Wayland spec, to keep compatibility between the two libraries.


@@ 24,6 23,7 @@ transition projects to any breaking changes I make along the way.*

## Features

- Client support
- All implementation done in Common Lisp from the socket up
- Enum values are translated into keywords
- Wayland protocol introspection


@@ 33,11 33,11 @@ transition projects to any breaking changes I make along the way.*

## Road map

Wayflan is currently only a communication library for Wayland clients, but
intends to be a full-duplex library for both Clients and Compositors. The
Wayflan project [tracker](https://todo.sr.ht/~shunter/wayflan) lists all
tickets to improve Wayflan, and other Common Lisp systems related to the Linux
desktop.
Wayflan is currently only a single-threaded communication library for Wayland
clients, but intends to be a full-duplex multi-threadable library for both
Clients and Compositors. The Wayflan project
[tracker](https://todo.sr.ht/~shunter/wayflan) lists all tickets to improve
Wayflan and other systems for the Freedesktop stack.

## Documentation



@@ 51,7 51,7 @@ desktop.

This is a brief version of the [Hello World](./examples/hello-world.lisp) example.

This snippet connects to a Wayland compositor to print all global variables the
This snippet connects to a Wayland server to print all global variables the
client can bind to:

```lisp


@@ 59,7 59,7 @@ client can bind to:
(use-package :wayflan-client)

(defun run ()
  ;; Try to connect to a compositor socket at $XDG_RUNTIME_DIR/$WAYLAND_DISPLAY.
  ;; Try to connect to a server socket at $XDG_RUNTIME_DIR/$WAYLAND_DISPLAY.
  ;; If $WAYLAND_DISPLAY describes an absolute path, connect to that directly.
  (with-open-display (display)
    ;; Create a registry to provide a list of all

M doc/API-Reference.md => doc/API-Reference.md +2 -2
@@ 92,7 92,7 @@ order each was defined, and identify which request or event to act on.

**Description:**

Represents a message from a client to the compositor
Represents a message from a client to the server

**Readers:**



@@ 106,7 106,7 @@ Represents a message from a client to the compositor

**Description:**

Represents a message from the compositor to a client
Represents a message from the server to a client

**Readers:**


M doc/Client-API-Reference.md => doc/Client-API-Reference.md +5 -5
@@ 2,7 2,7 @@

The wayflan-client package includes all symbols from the [wayflan
package](./API-Reference.md) plus the interface for connecting to, sending
messages to, and dispatching events from a compositor.
messages to, and dispatching events from a server.

The macro forms **define-interface**, **define-enum**, **define-request**, and
**define-event** are all used internally by `:wayflan-client-impl`, and are


@@ 36,7 36,7 @@ no value, return **nil**.

**Description:**

A representation of a resource in the Wayland compositor. All subclasses are an
A representation of a resource in the Wayland server. All subclasses are an
instance of __wl-interface-class__ except __wl-destroyed-proxy__.

**Readers:**


@@ 89,7 89,7 @@ internal Wayland protocol features.

**Description:**

Find and return a proxy known by the Wayland compositor by that name.
Find and return a proxy known by the Wayland server by that name.

## [Generic Function] **destroy-proxy** *proxy*



@@ 100,7 100,7 @@ Find and return a proxy known by the Wayland compositor by that name.
**Description:**

Mark the proxy for destruction and reclaim its ID for use by another proxy.
Destructor requests specialize on **destroy-proxy** to send the compositor the
Destructor requests specialize on **destroy-proxy** to send the server the
request message.

## [Generic Function] **wl-enum-value** *enum keyword* => *integer*


@@ 130,7 130,7 @@ keywords), according to *enum*.

## [Function] **wl-display-connect** *&optional name* => *display*

Connect to a Wayland compositor and return a __wl-display__ owning the
Connect to a Wayland server and return a __wl-display__ owning the
connection.

## [Function] **wl-display-disconnect** *display*

M src/client/client.lisp => src/client/client.lisp +2 -2
@@ 93,7 93,7 @@

(defclass wl-destroyed-proxy (wl-proxy)
  ()
  (:documentation "A proxy that has since been deleted by the compositor."))
  (:documentation "A proxy that has since been deleted by the server."))

(defclass wl-display (wl-proxy)
  ((%pathname :type pathname


@@ 104,7 104,7 @@
                 :reader %proxy-table)
   (%socket :type data-socket
            :initarg :socket :reader %wl-display-socket))
  (:documentation "A connection to the compositor that acts as a proxy to the wl_display singleton object")
  (:documentation "A connection to the server that acts as a proxy to the wl_display singleton object")
  (:version . 1)
  (:interface-name . "wl_display")
  (:metaclass wl-interface-class))

M src/client/packages.lisp => src/client/packages.lisp +10 -18
@@ 50,29 50,23 @@
           #:define-event)
  (:documentation "Wayland client and core protocol implementation.

Wayland is a protocol for a compositor to talk to its clients.
The compositor can be a standalone display server running on Linux kernel modesetting and evdev input devices, or an X application, or a Wayland client itself.
The clients can be traditional applications, X servers (rootless or fullscreen), or other display servers.
Wayland is a protocol for clients to talk to a display server to make themselves visible or get input from the user.
The server can be a standalone display server running on Linux kernel modesetting and evdev input devices, or an X application, or a Wayland client itself.

This package defines the client's interpretation of various CLOS classes, the event protocol, define- macros to implement wayland protocols, and the core Wayland protocol."))
This package contains symbols to drive the clientside implementation of the Wayland protocol."))

(defpackage #:xyz.shunter.wayflan.client.scanner
  (:use #:cl #:alexandria #:xyz.shunter.wayflan.client)
  (:export #:wl-include)
  (:documentation "PRIVATE: Wayland XML protocol definitions auto-wrapper.

This package defines WL-INCLUDE, a macro that transforms a Wayland protocol described in an XML file into wayflan definition forms.

PRIVATE: This package is private to Wayflan, and its API is susceptible to change. Please do not use this package in your own code."))
  (:documentation "PRIVATE: This package is private to Wayflan, and its API is susceptible to change. Please do not use this package in your own code."))

(defpackage #:xyz.shunter.wayflan.client.presentation-time
  (:use #:cl #:xyz.shunter.wayflan.client)
  (:nicknames #:wayflan-client.presentation-time)
  (:documentation "Wayland Presentation time protocol implementation.

Wayland is a protocol for a compositor to talk to its clients.
The compositor can be a standalone display server running on Linux kernel modesetting and evdev input devices, or an X application, or a Wayland client itself.
The clients can be traditional applications, X servers (rootless or fullscreen), or other display servers.
Wayland is a protocol for clients to talk to a display server to make themselves visible or get input from the user.
The server can be a standalone display server running on Linux kernel modesetting and evdev input devices, or an X application, or a Wayland client itself.

This package implements the stable Presentation Time protocol."))



@@ 81,9 75,8 @@ This package implements the stable Presentation Time protocol."))
  (:nicknames #:wayflan-client.viewporter)
  (:documentation "Wayland Viewporter protocol implementation.

Wayland is a protocol for a compositor to talk to its clients.
The compositor can be a standalone display server running on Linux kernel modesetting and evdev input devices, or an X application, or a Wayland client itself.
The clients can be traditional applications, X servers (rootless or fullscreen), or other display servers.
Wayland is a protocol for clients to talk to a display server to make themselves visible or get input from the user.
The server can be a standalone display server running on Linux kernel modesetting and evdev input devices, or an X application, or a Wayland client itself.

This package implements the stable Viewporter protocol."))



@@ 92,8 85,7 @@ This package implements the stable Viewporter protocol."))
  (:nicknames #:wayflan-client.xdg-shell)
  (:documentation "Wayland XDG shell protocol implementation.

Wayland is a protocol for a compositor to talk to its clients.
The compositor can be a standalone display server running on Linux kernel modesetting and evdev input devices, or an X application, or a Wayland client itself.
The clients can be traditional applications, X servers (rootless or fullscreen), or other display servers.
Wayland is a protocol for clients to talk to a display server to make themselves visible or get input from the user.
The server can be a standalone display server running on Linux kernel modesetting and evdev input devices, or an X application, or a Wayland client itself.

This package implements the stable XDG shell protocol."))

M src/packages.lisp => src/packages.lisp +4 -9
@@ 55,11 55,10 @@
    #:wl-parse)
  (:documentation "Wayland protocol and type information

Wayland is a protocol for a compositor to talk to its clients.
The compositor can be a standalone display server running on Linux kernel modesetting and evdev input devices, or an X application, or a Wayland client itself.
The clients can be traditional applications, X servers (rootless or fullscreen), or other display servers.
Wayland is a protocol for clients to talk to a display server to make themselves visible or get input from the user.
The server can be a standalone display server running on Linux kernel modesetting and evdev input devices, or an X application, or a Wayland client itself.

This package defines Wayland protocol CLOS objects, a function that parses a protocol document into CLOS, and a series of types of Wayland primitives."))
This package defines Wayland protocol CLOS objects, a function that parses a protocol document into CLOS, and a series of Wayland primitives as lisp types."))

(defpackage #:xyz.shunter.wayflan.ffi
  (:use #:cffi)


@@ 132,8 131,4 @@ This package defines Wayland protocol CLOS objects, a function that parses a pro
           #:read-wl-string
           #:read-wl-array
           #:with-incoming-message)
  (:documentation "PRIVATE: Wayland wire format marshalling.

The wayland-wire package defines utilities for communicating primitive data through a local address socket

PRIVATE: This package is private to Wayflan, and its API is susceptible to change. Please do not use this package in your own code."))
  (:documentation "PRIVATE: This package is private to Wayflan, and its API is susceptible to change. Please do not use this package in your own code."))

M src/protocol.lisp => src/protocol.lisp +2 -2
@@ 56,9 56,9 @@ Interfaces are message-based. Requests are actuated as server-bound messages, wh
          :initarg :args)))

(defclass wl-request (%wl-message) ()
  (:documentation "Represents a message from a client to the compositor"))
  (:documentation "Represents a message from a client to the server"))
(defclass wl-event (%wl-message) ()
  (:documentation "Represents a message from the compositor to a client"))
  (:documentation "Represents a message from the server to a client"))

(defclass wl-enum (%wl-named-object)
  ((%since :type wl-uint :reader wl-since

M src/wire.lisp => src/wire.lisp +1 -2
@@ 300,8 300,7 @@ in the circular buffer and return the number of iovecs used."
   (%input-fdbuf :initform (make-circular-buffer)
                :type (or circular-buffer null))
   (%output-fdbuf :initform (make-circular-buffer)
                 :type (or circular-buffer null)))
  (:documentation "A binary binary local socket connected to a Wayland compositor"))
                 :type (or circular-buffer null))))

(defun make-socket ()
  (let ((sockfd (socket +af-local+ +sock-stream+ 0)))