docs: Update README for clarity and structure

- Refine project description to emphasize foundational role of WLTurbo
- Reorganize sections for better flow: Overview, Features, Design Goals, Implementation Status
- Enhance performance targets and optimizations details
- Update usage example in Quick Start section
- Clarify contribution areas and remove outdated information

commit: 111649b1f3def6ff216191aa04d00eecbe14b435
author: bamen · 16mo ago · 2025-06-20 05:54 UTC
parent: 4a0dffe
signature: unsigned

1 file · +56 -53

M README.md +56 -53

@@ -1,33 +1,39 @@
1		-	# WLTurbo - High-Performance Wayland Client for Go
	1	+	# WLTurbo - Wayland Client Library for Go
2	2
3		-	🚀 Ultra-fast, zero-allocation Wayland client library optimized for gaming and real-time applications
	3	+	A performance-focused Wayland client library that provides the foundational protocol implementation for building Wayland applications and libraries.
4	4
5		-	## Features
	5	+	## Overview
	6	+
	7	+	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](https://github.com/bnema/libwldevices-go) which implement specific Wayland protocol extensions.
	8	+
	9	+	## Architecture
	10	+
	11	+	WLTurbo 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	+
	18	+	Higher-level protocol implementations (virtual input devices, output management, etc.) are intentionally left to specialized libraries that build on top of WLTurbo.
6	19
7		-	- 🎯 Sub-microsecond latency - < 500ns input event processing
8		-	- ⚡ Zero-allocation hot paths - No GC pressure during event handling
9		-	- 🎮 Gaming optimized - 360-500+ FPS support, 8000Hz device compatibility
10		-	- 🔒 Lock-free architecture - MPSC queues and atomic operations
11		-	- 🏎️ SIMD optimizations - Vectorized batch operations
12		-	- 📊 Cache-friendly - 64-byte aligned data structures
13		-	- 🔧 Go 1.24 ready - Leverages latest performance features
	20	+	## Features
14	21
15		-	## Performance Targets
	22	+	### Performance Optimizations
16	23
17		-	\| Metric \| Target \| Description \|
18		-	\|--------\|--------\|-------------\|
19		-	\| Input Latency \| < 125μs \| Input-to-dispatch (8000Hz polling rate) \|
20		-	\| Event Dispatch \| < 50ns \| Per-event processing time \|
21		-	\| Allocations \| 0 \| Zero allocations in steady state \|
22		-	\| GC Pause \| < 10μs \| Maximum garbage collection pause \|
23		-	\| Throughput \| 16,000+ \| Events per second capacity \|
	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
24	30
25		-	## Gaming Hardware Support
	31	+	### Design Goals
26	32
27		-	- 8000Hz Mice: Razer Viper 8K, Corsair Sabre RGB Pro
28		-	- 8000Hz Keyboards: Wooting 80HE with true analog scanning
29		-	- High-refresh displays: ASUS ROG Swift 500Hz, BenQ Zowie XL2566K
30		-	- VRR/G-Sync: Variable refresh rate awareness
	33	+	- Minimal allocations in hot paths
	34	+	- Efficient event dispatching
	35	+	- Clean API for protocol extensions
	36	+	- Foundation for high-performance Wayland applications
31	37
32	38		## Quick Start
33	39

@@ -35,18 +41,18 @@
35	41		package main
36	42
37	43		import (
38		-	"github.com/bnema/wlturbo"
	44	+	"github.com/bnema/wlturbo/wl"
39	45		)
40	46
41	47		func main() {
42	48		// Connect to Wayland display
43		-	display, err := wlturbo.Connect("")
	49	+	display, err := wl.Connect("")
44	50		if err != nil {
45	51		panic(err)
46	52		}
47	53		defer display.Close()
48	54
49		-	// Ultra-low latency event loop
	55	+	// Basic event loop
50	56		for {
51	57		if err := display.Dispatch(); err != nil {
52	58		break

@@ -55,33 +61,32 @@ func main() {
55	61		}
56	62		```
57	63
58		-	## Architecture
	64	+	For device control and input injection, use [libwldevices-go](https://github.com/bnema/libwldevices-go) which builds on top of WLTurbo.
59	65
60		-	WLTurbo is built with gaming performance in mind:
	66	+	## Implementation Status
61	67
62		-	- Lock-free Event Queue: MPSC ring buffer for zero-contention event handling
63		-	- Object Pool: Pre-allocated event objects to eliminate malloc overhead
64		-	- Direct Dispatch: Array-based handler lookup for objects < 1024
65		-	- Batch Processing: Process multiple events per syscall
66		-	- Memory Pool: Size-classed allocators for temporary buffers
	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
67	73
68		-	## Benchmarks
	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
69	79
70		-	```
71		-	BenchmarkEventDispatch-16 20000000 50.2 ns/op 0 B/op 0 allocs/op
72		-	BenchmarkMessageSend-16 40000000 25.1 ns/op 0 B/op 0 allocs/op
73		-	BenchmarkFDPassing-16 5000000 200.0 ns/op 0 B/op 0 allocs/op
74		-	```
	80	+	### Future Improvements
	81	+	- Performance benchmarks and validation
	82	+	- Additional optimizations based on profiling
	83	+	- Extended protocol object support as needed
75	84
76	85		## Requirements
77	86
78		-	- Go 1.24+ (for latest performance features)
79		-	- Linux (Wayland compositor required)
80		-	- Modern CPU (for SIMD optimizations)
81		-
82		-	## Status
83		-
84		-	🚧 Active Development - Core functionality complete, optimizations ongoing
	87	+	- Go 1.21+
	88	+	- Linux with Wayland compositor
	89	+	- Unix sockets support
85	90
86	91		## License
87	92

@@ -89,10 +94,8 @@ MIT License - see LICENSE file for details
89	94
90	95		## Contributing
91	96
92		-	PRs welcome! Please read CONTRIBUTING.md for guidelines.
93		-
94		-	Focus areas:
95		-	- Performance optimizations
96		-	- Gaming-specific features
97		-	- Protocol extension support
98		-	- Benchmark improvements⏎̸
	97	+	Contributions welcome! Areas of focus:
	98	+	- Performance improvements
	99	+	- Additional protocol object support
	100	+	- Documentation and examples
	101	+	- Benchmark suite⏎̸

@@ -1,33 +1,39 @@
1	-	# WLTurbo - High-Performance Wayland Client for Go	1	+	# WLTurbo - Wayland Client Library for Go
2			2
3	-	🚀 Ultra-fast, zero-allocation Wayland client library optimized for gaming and real-time applications	3	+	A performance-focused Wayland client library that provides the foundational protocol implementation for building Wayland applications and libraries.
4			4
5	-	## Features	5	+	## Overview
			6	+
			7	+	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](https://github.com/bnema/libwldevices-go) which implement specific Wayland protocol extensions.
			8	+
			9	+	## Architecture
			10	+
			11	+	WLTurbo 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	+
			18	+	Higher-level protocol implementations (virtual input devices, output management, etc.) are intentionally left to specialized libraries that build on top of WLTurbo.
6			19
7	-	- 🎯 Sub-microsecond latency - < 500ns input event processing	20	+	## Features
8	-	- ⚡ Zero-allocation hot paths - No GC pressure during event handling
9	-	- 🎮 Gaming optimized - 360-500+ FPS support, 8000Hz device compatibility
10	-	- 🔒 Lock-free architecture - MPSC queues and atomic operations
11	-	- 🏎️ SIMD optimizations - Vectorized batch operations
12	-	- 📊 Cache-friendly - 64-byte aligned data structures
13	-	- 🔧 Go 1.24 ready - Leverages latest performance features
14			21
15	-	## Performance Targets	22	+	### Performance Optimizations
16			23
17	-	\| Metric \| Target \| Description \|	24	+	- Zero-allocation event handling: For messages under 4KB
18	-	\|--------\|--------\|-------------\|	25	+	- Lock-free dispatcher: For object IDs < 1024 using atomic operations
19	-	\| Input Latency \| < 125μs \| Input-to-dispatch (8000Hz polling rate) \|	26	+	- Pre-allocated buffers: Reusable buffers to minimize allocations
20	-	\| Event Dispatch \| < 50ns \| Per-event processing time \|	27	+	- Direct array indexing: Fast opcode lookup for common cases
21	-	\| Allocations \| 0 \| Zero allocations in steady state \|	28	+	- Buffer pooling: sync.Pool for temporary allocations
22	-	\| GC Pause \| < 10μs \| Maximum garbage collection pause \|	29	+	- File descriptor passing: Efficient shared memory via SCM_RIGHTS
23	-	\| Throughput \| 16,000+ \| Events per second capacity \|
24			30
25	-	## Gaming Hardware Support	31	+	### Design Goals
26			32
27	-	- 8000Hz Mice: Razer Viper 8K, Corsair Sabre RGB Pro	33	+	- Minimal allocations in hot paths
28	-	- 8000Hz Keyboards: Wooting 80HE with true analog scanning	34	+	- Efficient event dispatching
29	-	- High-refresh displays: ASUS ROG Swift 500Hz, BenQ Zowie XL2566K	35	+	- Clean API for protocol extensions
30	-	- VRR/G-Sync: Variable refresh rate awareness	36	+	- Foundation for high-performance Wayland applications
31			37
32		## Quick Start	38		## Quick Start
33			39

@@ -35,18 +41,18 @@
35		package main	41		package main
36			42
37		import (	43		import (
38	-	"github.com/bnema/wlturbo"	44	+	"github.com/bnema/wlturbo/wl"
39		)	45		)
40			46
41		func main() {	47		func main() {
42		// Connect to Wayland display	48		// Connect to Wayland display
43	-	display, err := wlturbo.Connect("")	49	+	display, err := wl.Connect("")
44		if err != nil {	50		if err != nil {
45		panic(err)	51		panic(err)
46		}	52		}
47		defer display.Close()	53		defer display.Close()
48			54
49	-	// Ultra-low latency event loop	55	+	// Basic event loop
50		for {	56		for {
51		if err := display.Dispatch(); err != nil {	57		if err := display.Dispatch(); err != nil {
52		break	58		break

@@ -55,33 +61,32 @@ func main() {
55		}	61		}
56		```	62		```
57			63
58	-	## Architecture	64	+	For device control and input injection, use [libwldevices-go](https://github.com/bnema/libwldevices-go) which builds on top of WLTurbo.
59			65
60	-	WLTurbo is built with gaming performance in mind:	66	+	## Implementation Status
61			67
62	-	- Lock-free Event Queue: MPSC ring buffer for zero-contention event handling	68	+	### Core Protocol ✅
63	-	- Object Pool: Pre-allocated event objects to eliminate malloc overhead	69	+	- Display, Registry, Compositor, Surface, Seat, Region
64	-	- Direct Dispatch: Array-based handler lookup for objects < 1024	70	+	- Event dispatching and handler registration
65	-	- Batch Processing: Process multiple events per syscall	71	+	- File descriptor passing for shared memory
66	-	- Memory Pool: Size-classed allocators for temporary buffers	72	+	- Context-based proxy management
67			73
68	-	## Benchmarks	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
69			79
70	-	```	80	+	### Future Improvements
71	-	BenchmarkEventDispatch-16 20000000 50.2 ns/op 0 B/op 0 allocs/op	81	+	- Performance benchmarks and validation
72	-	BenchmarkMessageSend-16 40000000 25.1 ns/op 0 B/op 0 allocs/op	82	+	- Additional optimizations based on profiling
73	-	BenchmarkFDPassing-16 5000000 200.0 ns/op 0 B/op 0 allocs/op	83	+	- Extended protocol object support as needed
74	-	```
75			84
76		## Requirements	85		## Requirements
77			86
78	-	- Go 1.24+ (for latest performance features)	87	+	- Go 1.21+
79	-	- Linux (Wayland compositor required)	88	+	- Linux with Wayland compositor
80	-	- Modern CPU (for SIMD optimizations)	89	+	- Unix sockets support
81	-
82	-	## Status
83	-
84	-	🚧 Active Development - Core functionality complete, optimizations ongoing
85			90
86		## License	91		## License
87			92

@@ -89,10 +94,8 @@ MIT License - see LICENSE file for details
89			94
90		## Contributing	95		## Contributing
91			96
92	-	PRs welcome! Please read CONTRIBUTING.md for guidelines.	97	+	Contributions welcome! Areas of focus:
93	-		98	+	- Performance improvements
94	-	Focus areas:	99	+	- Additional protocol object support
95	-	- Performance optimizations	100	+	- Documentation and examples
96	-	- Gaming-specific features	101	+	- Benchmark suite⏎̸
97	-	- Protocol extension support
98	-	- Benchmark improvements⏎̸