aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authoronur1 <onur1@onurgunduz.com>2023-01-01 18:44:45 +0100
committeronur1 <onur1@onurgunduz.com>2023-01-01 18:44:45 +0100
commit77e13c055fdc76ff9babbb43754a8f8e44ca6128 (patch)
tree298ba0734bf93cee47aad6150c9ffcd4ca3d87dc
parent02387a1dc1ec156e0613920645cf47a51a04a930 (diff)
downloadmuxer-77e13c055fdc76ff9babbb43754a8f8e44ca6128.tar.gz
muxer-77e13c055fdc76ff9babbb43754a8f8e44ca6128.zip
Add documentation
-rw-r--r--binproto.go11
-rw-r--r--message.go6
-rw-r--r--reader.go11
-rw-r--r--writer.go7
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 {
diff --git a/message.go b/message.go
index 1ffa919..e66b731 100644
--- a/message.go
+++ b/message.go
@@ -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,
diff --git a/reader.go b/reader.go
index a955b0d..c14100e 100644
--- a/reader.go
+++ b/reader.go
@@ -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)
diff --git a/writer.go b/writer.go
index fdfa5ec..df5c134 100644
--- a/writer.go
+++ b/writer.go
@@ -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 {