]>
Commit | Line | Data |
---|---|---|
bae9f6d2 JC |
1 | # Yamux |
2 | ||
3 | Yamux (Yet another Multiplexer) is a multiplexing library for Golang. | |
4 | It relies on an underlying connection to provide reliability | |
5 | and ordering, such as TCP or Unix domain sockets, and provides | |
6 | stream-oriented multiplexing. It is inspired by SPDY but is not | |
7 | interoperable with it. | |
8 | ||
9 | Yamux 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 | ||
25 | For complete documentation, see the associated [Godoc](http://godoc.org/github.com/hashicorp/yamux). | |
26 | ||
27 | ## Specification | |
28 | ||
29 | The full specification for Yamux is provided in the `spec.md` file. | |
30 | It can be used as a guide to implementors of interoperable libraries. | |
31 | ||
32 | ## Usage | |
33 | ||
34 | Using Yamux is remarkably simple: | |
35 | ||
36 | ```go | |
37 | ||
38 | func 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 | ||
61 | func 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 |