diff options
| author | onur1 <onur1@onurgunduz.com> | 2023-01-01 18:44:45 +0100 |
|---|---|---|
| committer | onur1 <onur1@onurgunduz.com> | 2023-01-01 18:44:45 +0100 |
| commit | 77e13c055fdc76ff9babbb43754a8f8e44ca6128 (patch) | |
| tree | 298ba0734bf93cee47aad6150c9ffcd4ca3d87dc | |
| parent | 02387a1dc1ec156e0613920645cf47a51a04a930 (diff) | |
| download | muxer-77e13c055fdc76ff9babbb43754a8f8e44ca6128.tar.gz muxer-77e13c055fdc76ff9babbb43754a8f8e44ca6128.zip | |
Add documentation
| -rw-r--r-- | binproto.go | 11 | ||||
| -rw-r--r-- | message.go | 6 | ||||
| -rw-r--r-- | reader.go | 11 | ||||
| -rw-r--r-- | writer.go | 7 |
4 files changed, 32 insertions, 3 deletions
diff --git a/binproto.go b/binproto.go index 6b2ca54..016c87c 100644 --- a/binproto.go +++ b/binproto.go @@ -7,6 +7,10 @@ import ( "net/textproto" ) +// A Conn represents a binary network protocol connection. +// It consists of a Reader and Writer to manage I/O +// and a Pipeline (which is borrowed from textproto) to sequence +// concurrent requests on the connection. type Conn struct { Reader Writer @@ -14,6 +18,7 @@ type Conn struct { conn io.ReadWriteCloser } +// NewConn returns a new Conn using conn for I/O. func NewConn(conn io.ReadWriteCloser) *Conn { r, w := NewReaderSize(bufio.NewReader(conn), 16), NewWriter(bufio.NewWriter(conn)) return &Conn{ @@ -23,6 +28,9 @@ func NewConn(conn io.ReadWriteCloser) *Conn { } } +// Send is a convenience method that sends a variable number of messages +// after waiting its turn in the pipeline. +// Send returns the id of the command, for use with StartResponse and EndResponse. func (c *Conn) Send(m ...*Message) (id uint, err error) { id = c.Next() c.StartRequest(id) @@ -34,10 +42,13 @@ func (c *Conn) Send(m ...*Message) (id uint, err error) { return id, nil } +// Close closes the connection. func (c *Conn) Close() error { return c.conn.Close() } +// Dial connects to the given address on the given network using net.Dial +// and then returns a new Conn for the connection. func Dial(network, addr string) (*Conn, error) { c, err := net.Dial(network, addr) if err != nil { @@ -1,11 +1,17 @@ package binproto +// A Message represents a single binproto message. +// +// Each message starts with an header which is a varint encoded +// unsigned 64-bit integer which consists of an ID (first 60-bits) and +// a Channel number (last 4-bits), the rest of the message is payload. type Message struct { ID int Channel rune Data []byte } +// NewMessage returns a new Message. func NewMessage(id int, ch rune, data []byte) *Message { return &Message{ ID: id, @@ -5,6 +5,8 @@ import ( "io" ) +// A Reader implements convenience methods for reading requests +// or responses from a binary protocol network connection. type Reader struct { rd io.Reader r, w int @@ -34,10 +36,16 @@ var ( ErrMessageMalformed = errors.New("binproto: message malformed") ) +// NewReader returns a new Reader reading from r. +// +// By default, a Reader allocates `4096` bytes for its internal buffer, +// and will process what's inside the buffer as long as its size +// is greater than this limit. func NewReader(rd io.Reader) *Reader { return NewReaderSize(rd, defaultBufSize) } +// NewReaderSize returns a new Reader with the specified buffer size. func NewReaderSize(rd io.Reader, size int) *Reader { if size < minReadBufferSize { size = minReadBufferSize @@ -87,6 +95,7 @@ func (b *Reader) fill() { b.err = io.ErrNoProgress } +// ReadMessage reads a single message from r. func (b *Reader) ReadMessage() (message *Message, err error) { for { if b.err != nil { @@ -141,6 +150,8 @@ func (b *Reader) ReadMessage() (message *Message, err error) { return } +// Reset resets this Reader with the new source r, using +// the existing buffer. func (b *Reader) Reset(r io.Reader) { if b.buf == nil { b.buf = make([]byte, defaultBufSize) @@ -3,19 +3,20 @@ package binproto import ( "bufio" "encoding/binary" - "math" ) -var maxID = int(math.Pow(2, 60)) - 1 - +// A Writer implements convenience methods for writing +// requests or responses to a binary protocol network connection. type Writer struct { wd *bufio.Writer } +// NewWriter returns a new Writer writing to w. func NewWriter(wd *bufio.Writer) *Writer { return &Writer{wd: wd} } +// WriteMessage writes a variable number of messages to w. func (w *Writer) WriteMessage(messages ...*Message) error { var err error if len(messages) == 1 { |
