README.md
1# Yamux
2
3Yamux (Yet another Multiplexer) is a multiplexing library for Golang.
4It relies on an underlying connection to provide reliability
5and ordering, such as TCP or Unix domain sockets, and provides
6stream-oriented multiplexing. It is inspired by SPDY but is not
7interoperable with it.
8
9Yamux features include:
10
11* Bi-directional streams
12 * Streams can be opened by either client or server
13 * Useful for NAT traversal
14 * Server-side push support
15* Flow control
16 * Avoid starvation
17 * Back-pressure to prevent overwhelming a receiver
18* Keep Alives
19 * Enables persistent connections over a load balancer
20* Efficient
21 * Enables thousands of logical streams with low overhead
22
23## Documentation
24
25For complete documentation, see the associated [Godoc](http://godoc.org/github.com/hashicorp/yamux).
26
27## Specification
28
29The full specification for Yamux is provided in the `spec.md` file.
30It can be used as a guide to implementors of interoperable libraries.
31
32## Usage
33
34Using Yamux is remarkably simple:
35
36```go
37
38func client() {
39 // Get a TCP connection
40 conn, err := net.Dial(...)
41 if err != nil {
42 panic(err)
43 }
44
45 // Setup client side of yamux
46 session, err := yamux.Client(conn, nil)
47 if err != nil {
48 panic(err)
49 }
50
51 // Open a new stream
52 stream, err := session.Open()
53 if err != nil {
54 panic(err)
55 }
56
57 // Stream implements net.Conn
58 stream.Write([]byte("ping"))
59}
60
61func server() {
62 // Accept a TCP connection
63 conn, err := listener.Accept()
64 if err != nil {
65 panic(err)
66 }
67
68 // Setup server side of yamux
69 session, err := yamux.Server(conn, nil)
70 if err != nil {
71 panic(err)
72 }
73
74 // Accept a stream
75 stream, err := session.Accept()
76 if err != nil {
77 panic(err)
78 }
79
80 // Listen for a message
81 buf := make([]byte, 4)
82 stream.Read(buf)
83}
84
85```
86
87