aboutsummaryrefslogtreecommitdiff
path: root/README.md
blob: 32ff1ef47d68a0c7df336d8c7df8f9fa4b7cc702 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
# muxer

Minimal binary messaging protocol.

## Installation

```sh
go get git.onurgunduz.com/muxer@latest
```

## Usage

### Writing a message

Create a writer around a `bufio.Writer`.

```go
var output bytes.Buffer
writer := muxer.NewWriter(bufio.NewWriter(&output))
message := muxer.NewMessage(42, 3, []byte("hello"))

if err := writer.WriteMessage(message); err != nil {
	log.Fatal(err)
}
```

`WriteMessage` flushes the buffer before returning. Pass multiple messages to write a batch.

### Reading a message

Create a reader around any `io.Reader`. This reads the message written above:

```go
reader := muxer.NewReader(&output)
var received muxer.Message

if err := reader.ReadMessage(&received); err != nil {
	log.Fatal(err)
}
fmt.Printf("%d %d %s\n", received.ID, received.Type, received.Data)
```

`ReadMessage` returns `io.EOF` when the source ends. The default buffer size is 4096 bytes; use `NewReaderSize` when messages need a larger buffer.

The returned `Data` slice shares the reader's storage. Process it before the next read.

### Using a TCP connection

For a server listening on `127.0.0.1:4242` that speaks the muxer protocol and replies to each message:

```go
conn, err := muxer.Dial("tcp", "127.0.0.1:4242")
if err != nil {
	log.Fatal(err)
}
defer conn.Close()

if _, err := conn.Send(muxer.NewMessage(42, 3, []byte("hello"))); err != nil {
	log.Fatal(err)
}

var response muxer.Message
if err := conn.ReadMessage(&response); err != nil {
	log.Fatal(err)
}
fmt.Printf("%d %d %s\n", response.ID, response.Type, response.Data)
```

`NewConn` wraps an accepted connection or another `io.ReadWriteCloser`.

`Send` can write several messages at once and can be called concurrently. Use one reading goroutine per connection; direct `Reader` and `Writer` calls are not safe for concurrent use.

## Message structure

```
┌──────────────────────────────────────────────┐
│ length | channel ID × message type │ payload │
└──────────────────────────────────────────────┘
           └─ 60-bits   └─ 4-bits
```

## Benchmarks

```
goos: darwin
goarch: arm64
pkg: git.onurgunduz.com/muxer
cpu: Apple M4 Pro
BenchmarkWriter_64B-12          98590449                12.05 ns/op     5309.66 MB/s           0 B/op          0 allocs/op
BenchmarkWriter_4KB-12          14346594                80.00 ns/op     51198.63 MB/s          0 B/op          0 allocs/op
BenchmarkWriter_1MB-12             74955             15931 ns/op        65819.47 MB/s         14 B/op          0 allocs/op
BenchmarkReader_64B-12          70582526                16.24 ns/op     3941.01 MB/s           0 B/op          0 allocs/op
BenchmarkReader_4KB-12          15629764                78.92 ns/op     51903.93 MB/s          0 B/op          0 allocs/op
BenchmarkReader_1MB-12             38365             31480 ns/op        33309.32 MB/s          0 B/op          0 allocs/op
```