vendor/github.com/hashicorp/yamux/README.md

   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