Merge pull request #1

* 添加pubsub核心实现，包括Broker、Publisher、Subscriber组件及完整测试用例

* 优化基准测试并添加示例代码：重构基准测试用例，增加通道容量和超时场景测试，添加快速入门示例，更新README文档

* 优化README文档描述：精简核心特性说明，突出实时Pub/Sub场景应用，调整措辞更精准体现库的无状态特性

* 重构项目结构：将核心代码移至pubsub子目录，调整示例代码路径，更新导入路径引用

Author: F2077

.gitignore

@@ -11,11 +11,8 @@
 # Test binary, built with `go test -c`
 *.test
 
-# Code coverage profiles and other test artifacts
+# Output of the go coverage tool, specifically when used with LiteIDE
 *.out
-coverage.*
-*.coverprofile
-profile.cov
 
 # Dependency directories (remove the comment below to include it)
 # vendor/
@@ -26,7 +23,4 @@ go.work.sum
 
 # env file
 .env
-
-# Editor/IDE
-# .idea/
-# .vscode/
+.idea

README.md

@@ -1,2 +1,123 @@
 # go-pubsub
-A lightweight real-time Pub-Sub library for Go.
+
+<img src="logo.png" width="128px" alt="logo">
+
+Lightweight, real-time Pub/Sub for Go—perfect for transient data flows like live dashboards, game events, short-lived alerts, and real-time streaming-media packet fan-out. It’s pure fire-and-forget: zero persistence, no delivery guarantees, just ultra-fast one-way messaging.
+
+---
+
+## Installation
+
+```bash
+go get github.com/F2077/go-pubsub
+```
+
+## Quick Start
+
+```go
+package main
+
+import (
+	"fmt"
+	"github.com/F2077/go-pubsub/pubsub"
+	"time"
+)
+
+func main() {
+	// 1. Create a broker (supports generics)
+	broker, _ := pubsub.NewBroker[string]()
+
+	// 2. Create a publisher
+	publisher := pubsub.NewPublisher[string](broker)
+
+	// 3. Create a subscriber
+	subscriber := pubsub.NewSubscriber[string](broker)
+
+	// 4. Subscribe to a topic with buffer size and timeout
+	sub, _ := subscriber.Subscribe("alerts",
+		pubsub.WithChannelSize[string](pubsub.Medium), // Buffer 100 messages
+		pubsub.WithTimeout[string](5*time.Second),     // Auto-close if idle
+	)
+	defer func(sub *pubsub.Subscription[string]) {
+		_ = sub.Close()
+	}(sub)
+
+	// 5. Publish a message
+	go func() {
+		_ = publisher.Publish("alerts", "CPU over 90%!")
+	}()
+
+	// 6. Listen for messages or timeouts
+	select {
+	case msg := <-sub.Ch:
+		fmt.Println("Received:", msg) // Output: "CPU over 90%!"
+	case err := <-sub.ErrCh:
+		fmt.Println("Error:", err) // e.g., timeout
+	}
+}
+
+```
+
+## Key Features
+
+- 🚀 **Zero Persistence**: Messages vanish if channels are full or subscribers time out.
+- ⏱️ **Auto-Expiry**: Idle subscriptions close automatically (configurable timeout).
+- 🔒 **Concurrency-Safe**: Efficient locking for high concurrency.
+- 📦 **Capacity Control**: Set max subscriptions per broker (prevents memory leaks).
+- 📡 **Topic-Based**: Simple publish/subscribe with string topics.
+
+## Advanced Configuration
+
+### Custom Broker
+
+```go
+broker, _ := pubsub.NewBroker[string](
+pubsub.WithCapacity(5000), // Max 5000 topics
+pubsub.WithLogger(customLogger), // Inject your logger
+pubsub.WithId("broker-1"), // Custom broker ID
+)
+```
+
+### Subscriber Options
+
+```go
+// Subscribe with custom settings
+sub, _ := subscriber.Subscribe("metrics",
+pubsub.WithChannelSize[string](pubsub.Huge), // 1000-message buffer
+pubsub.WithTimeout[string](10 * time.Second), // Timeout after 10s inactivity
+)
+```
+
+## When to Use
+
+- ✅ Real-time pub-sub
+- ✅ Low-latency gaming/live events
+- ❌ **Not for**: Persistent queues, guaranteed delivery.
+
+## Performance Notes
+
+- 🔥 **Fast fan-out**: Optimized for many subscribers per topic.
+- ⚠️ **No backpressure**: Full channels drop messages silently.
+
+---
+
+## Benchmark Results
+
+_All benchmarks run on_ **goos: windows**, **goarch: amd64**, **pkg: github.com/F2077/go-pubsub**, **cpu: Intel(R) Core(TM) i7-10700F CPU @ 2.90GHz**
+
+| Benchmark                                        | Iterations |           ns/op | B/op | allocs/op |
+|--------------------------------------------------|-----------:|----------------:|-----:|----------:|
+| BenchmarkPublishSingleSubscriber-16              |  5 188 107 |     233.0 ns/op |   96 |         2 |
+| BenchmarkMultipleSubscribers-16                  |    143 594 |     8 089 ns/op |   96 |         2 |
+| BenchmarkMultiPublisherSingleSubscriber-16       |    259 663 |     4 732 ns/op |  776 |        21 |
+| BenchmarkMultiPublisherMultipleSubscribers-16    |     67 593 |    17 823 ns/op |  776 |        21 |
+| BenchmarkUltraLargeSubscribersSinglePublisher-16 |        471 | 2 846 125 ns/op |   96 |         2 |
+| BenchmarkPublishChannelSizes/Small-16            |  5 271 156 |     230.2 ns/op |   96 |         2 |
+| BenchmarkPublishChannelSizes/Medium-16           |  5 134 640 |     229.5 ns/op |   96 |         2 |
+| BenchmarkPublishChannelSizes/Large-16            |  5 238 266 |     231.8 ns/op |   96 |         2 |
+| BenchmarkPublishWithTimeout-16                   |  1 345 124 |     861.1 ns/op |  507 |         7 |
+| BenchmarkHighLoadParallel-16                     |     14 728 |    83 785 ns/op |  100 |         2 |
+
+---
+
+**Contributions welcome!** Report bugs or suggest features via issues.

cmd/quickstart/main.go

@@ -0,0 +1,40 @@
+package main
+
+import (
+	"fmt"
+	"github.com/F2077/go-pubsub/pubsub"
+	"time"
+)
+
+func main() {
+	// 1. Create a broker (supports generics)
+	broker, _ := pubsub.NewBroker[string]()
+
+	// 2. Create a publisher
+	publisher := pubsub.NewPublisher[string](broker)
+
+	// 3. Create a subscriber
+	subscriber := pubsub.NewSubscriber[string](broker)
+
+	// 4. Subscribe to a topic with buffer size and timeout
+	sub, _ := subscriber.Subscribe("alerts",
+		pubsub.WithChannelSize[string](pubsub.Medium), // Buffer 100 messages
+		pubsub.WithTimeout[string](5*time.Second),     // Auto-close if idle
+	)
+	defer func(sub *pubsub.Subscription[string]) {
+		_ = sub.Close()
+	}(sub)
+
+	// 5. Publish a message
+	go func() {
+		_ = publisher.Publish("alerts", "CPU over 90%!")
+	}()
+
+	// 6. Listen for messages or timeouts
+	select {
+	case msg := <-sub.Ch:
+		fmt.Println("Received:", msg) // Output: "CPU over 90%!"
+	case err := <-sub.ErrCh:
+		fmt.Println("Error:", err) // e.g., timeout
+	}
+}

go.mod

@@ -0,0 +1,14 @@
+module github.com/F2077/go-pubsub
+
+go 1.21
+
+require (
+	github.com/google/uuid v1.6.0
+	github.com/stretchr/testify v1.10.0
+)
+
+require (
+	github.com/davecgh/go-spew v1.1.1 // indirect
+	github.com/pmezard/go-difflib v1.0.0 // indirect
+	gopkg.in/yaml.v3 v3.0.1 // indirect
+)

go.sum

@@ -0,0 +1,12 @@
+github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
+github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
+github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
+github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
+github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/stretchr/testify v1.10.0 h1:Xv5erBjTwe/5IxqUQTdXv5kgmIvbHo3QQyRwhJsOfJA=
+github.com/stretchr/testify v1.10.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=