README.md Raw History Folder

WLTurbo - Wayland Client Library for Go

A performance-focused Wayland client library that provides the foundational protocol implementation for building Wayland applications and libraries.

Overview

WLTurbo is a low-level Wayland client library that handles core protocol communication. It serves as the base layer for higher-level libraries like libwldevices-go which implement specific Wayland protocol extensions.

Architecture

WLTurbo provides the foundational Wayland client infrastructure:

Core Protocol Objects: Display, Registry, Compositor, Surface, Seat, Region
Event Dispatching: Efficient routing of Wayland events to handlers
Connection Management: Unix socket communication with the compositor
Memory Management: Shared memory support via file descriptor passing

Higher-level protocol implementations (virtual input devices, output management, etc.) are intentionally left to specialized libraries that build on top of WLTurbo.

Features

Performance Optimizations

Zero-allocation event handling: For messages under 4KB
Lock-free dispatcher: For object IDs < 1024 using atomic operations
Pre-allocated buffers: Reusable buffers to minimize allocations
Direct array indexing: Fast opcode lookup for common cases
Buffer pooling: sync.Pool for temporary allocations
File descriptor passing: Efficient shared memory via SCM_RIGHTS

Design Goals

Minimal allocations in hot paths
Efficient event dispatching
Clean API for protocol extensions
Foundation for high-performance Wayland applications

Quick Start

package main

import (
    "github.com/bnema/wlturbo/wl"
)

func main() {
    // Connect to Wayland display
    display, err := wl.Connect("")
    if err != nil {
        panic(err)
    }
    defer display.Close()

    // Basic event loop
    for {
        if err := display.Dispatch(); err != nil {
            break
        }
    }
}

For device control and input injection, use libwldevices-go which builds on top of WLTurbo.

Implementation Status

Core Protocol ✅

Display, Registry, Compositor, Surface, Seat, Region
Event dispatching and handler registration
File descriptor passing for shared memory
Context-based proxy management

Optimizations ✅

Zero-allocation event handling (messages < 4KB)
Lock-free dispatcher for common cases
Pre-allocated and pooled buffers
Efficient event routing

Future Improvements

Performance benchmarks and validation
Additional optimizations based on profiling
Extended protocol object support as needed

Requirements

Go 1.21+
Linux with Wayland compositor
Unix sockets support

License

MIT License - see LICENSE file for details

Contributing

Contributions welcome! Areas of focus:

Performance improvements
Additional protocol object support
Documentation and examples
Benchmark suite

source

1# WLTurbo - Wayland Client Library for Go
2
3A performance-focused Wayland client library that provides the foundational protocol implementation for building Wayland applications and libraries.
4
5## Overview
6
7WLTurbo is a low-level Wayland client library that handles core protocol communication. It serves as the base layer for higher-level libraries like [libwldevices-go](https://github.com/bnema/libwldevices-go) which implement specific Wayland protocol extensions.
8
9## Architecture
10
11WLTurbo provides the foundational Wayland client infrastructure:
12
13- **Core Protocol Objects**: Display, Registry, Compositor, Surface, Seat, Region
14- **Event Dispatching**: Efficient routing of Wayland events to handlers
15- **Connection Management**: Unix socket communication with the compositor
16- **Memory Management**: Shared memory support via file descriptor passing
17
18Higher-level protocol implementations (virtual input devices, output management, etc.) are intentionally left to specialized libraries that build on top of WLTurbo.
19
20## Features
21
22### Performance Optimizations
23
24- **Zero-allocation event handling**: For messages under 4KB
25- **Lock-free dispatcher**: For object IDs < 1024 using atomic operations  
26- **Pre-allocated buffers**: Reusable buffers to minimize allocations
27- **Direct array indexing**: Fast opcode lookup for common cases
28- **Buffer pooling**: sync.Pool for temporary allocations
29- **File descriptor passing**: Efficient shared memory via SCM_RIGHTS
30
31### Design Goals
32
33- Minimal allocations in hot paths
34- Efficient event dispatching
35- Clean API for protocol extensions
36- Foundation for high-performance Wayland applications
37
38## Quick Start
39
40```go
41package main
42
43import (
44    "github.com/bnema/wlturbo/wl"
45)
46
47func main() {
48    // Connect to Wayland display
49    display, err := wl.Connect("")
50    if err != nil {
51        panic(err)
52    }
53    defer display.Close()
54
55    // Basic event loop
56    for {
57        if err := display.Dispatch(); err != nil {
58            break
59        }
60    }
61}
62```
63
64For device control and input injection, use [libwldevices-go](https://github.com/bnema/libwldevices-go) which builds on top of WLTurbo.
65
66## Implementation Status
67
68### Core Protocol ✅
69- Display, Registry, Compositor, Surface, Seat, Region
70- Event dispatching and handler registration
71- File descriptor passing for shared memory
72- Context-based proxy management
73
74### Optimizations ✅
75- Zero-allocation event handling (messages < 4KB)
76- Lock-free dispatcher for common cases
77- Pre-allocated and pooled buffers
78- Efficient event routing
79
80### Future Improvements
81- Performance benchmarks and validation
82- Additional optimizations based on profiling
83- Extended protocol object support as needed
84
85## Requirements
86
87- **Go 1.21+**
88- **Linux** with Wayland compositor
89- **Unix sockets** support
90
91## License
92
93MIT License - see LICENSE file for details
94
95## Contributing
96
97Contributions welcome! Areas of focus:
98- Performance improvements
99- Additional protocol object support
100- Documentation and examples
101- Benchmark suite

README.md RawHistoryFolder