msgio

README

msgio - 消息 IO

这是一个简单的包,用于帮助读写长度分隔的切片。它对构建网络协议很有帮助。

使用方法

Reading

import "github.com/dep2p/libp2p/p2plib/msgio"
rdr := ... // some reader from a wire
mrdr := msgio.NewReader(rdr)

for {
  msg, err := mrdr.ReadMsg()
  if err != nil {
    return err
  }

  doSomething(msg)
}

Writing

import "github.com/dep2p/libp2p/p2plib/msgio"
wtr := genReader()
mwtr := msgio.NewWriter(wtr)

for {
  msg := genMessage()
  err := mwtr.WriteMsg(msg)
  if err != nil {
    return err
  }
}

Duplex

import "github.com/dep2p/libp2p/p2plib/msgio"
rw := genReadWriter()
mrw := msgio.NewReadWriter(rw)

for {
  msg, err := mrdr.ReadMsg()
  if err != nil {
    return err
  }

  // echo it back :)
  err = mwtr.WriteMsg(msg)
  if err != nil {
    return err
  }
}

Documentation

Index

• Variables
• func LimitedReader(r io.Reader) (io.Reader, error)
• func ReadLen(r io.Reader, buf []byte) (int, error)
• func WriteLen(w io.Writer, l int) error
• type LimitedWriter
  • func NewLimitedWriter(w io.Writer) *LimitedWriter
  • func (w *LimitedWriter) Flush() error
  • func (w *LimitedWriter) Write(buf []byte) (n int, err error)
• type ReadCloser
  • func NewReader(r io.Reader) ReadCloser
  • func NewReaderSize(r io.Reader, maxMessageSize int) ReadCloser
  • func NewReaderSizeWithPool(r io.Reader, maxMessageSize int, p *pool.BufferPool) ReadCloser
  • func NewReaderWithPool(r io.Reader, p *pool.BufferPool) ReadCloser
  • func NewVarintReader(r io.Reader) ReadCloser
  • func NewVarintReaderSize(r io.Reader, maxMessageSize int) ReadCloser
  • func NewVarintReaderSizeWithPool(r io.Reader, maxMessageSize int, p *pool.BufferPool) ReadCloser
  • func NewVarintReaderWithPool(r io.Reader, p *pool.BufferPool) ReadCloser
• type ReadWriteCloser
  • func Combine(w Writer, r Reader) ReadWriteCloser
  • func NewReadWriter(rw io.ReadWriter) ReadWriteCloser
• type ReadWriter
• type Reader
• type WriteCloser
  • func NewVarintWriter(w io.Writer) WriteCloser
  • func NewVarintWriterWithPool(w io.Writer, p *pool.BufferPool) WriteCloser
  • func NewWriter(w io.Writer) WriteCloser
  • func NewWriterWithPool(w io.Writer, p *pool.BufferPool) WriteCloser
• type Writer

Variables

var ErrMsgTooLarge = errors.New("message too large")

ErrMsgTooLarge 当消息长度过大时返回此错误

var NBO = binary.BigEndian

NBO 是网络字节序

Functions

func LimitedReader

func LimitedReader(r io.Reader) (io.Reader, error)

LimitedReader 使用 msgio 帧读取器包装一个 io.Reader。 当消息长度读取完成时，LimitedReader 将返回一个带有 io.EOF 的读取器。 参数:

• r: 输入的 io.Reader

返回值:

• io.Reader: 限制长度的读取器
• error: 错误信息

func ReadLen

func ReadLen(r io.Reader, buf []byte) (int, error)

ReadLen 从指定的读取器中读取长度 参数:

• r: 读取器接口
• buf: 用于存储读取数据的缓冲区，如果为nil则创建新的缓冲区

返回值:

• int: 读取到的长度值
• error: 读取过程中的错误信息

示例:

l, err := ReadLen(r, nil)
_, err := ReadLen(r, buf)

func WriteLen

func WriteLen(w io.Writer, l int) error

WriteLen 将长度写入指定的写入器 参数:

• w: 写入器接口
• l: 要写入的长度值

返回值:

• error: 写入过程中的错误信息

Types

type LimitedWriter

type LimitedWriter struct {
	W io.Writer    // 底层写入器
	B bytes.Buffer // 缓冲区
	M sync.Mutex   // 互斥锁
}

LimitedWriter 实现了一个带缓冲的限制长度写入器

func NewLimitedWriter

func NewLimitedWriter(w io.Writer) *LimitedWriter

NewLimitedWriter 使用 msgio 帧写入器包装一个 io.Writer。 它是 LimitedReader 的反向操作:它会缓冲所有写入直到调用"Flush"。 当调用 Flush 时，它会先写入缓冲区大小，然后刷新缓冲区，重置缓冲区，并开始接受更多的传入写入。 参数:

• w: 输出的 io.Writer

返回值:

• *LimitedWriter: 限制长度的写入器

func (*LimitedWriter) Flush

func (w *LimitedWriter) Flush() error

Flush 将缓冲区的数据写入底层写入器 返回值:

• error: 错误信息

func (*LimitedWriter) Write

func (w *LimitedWriter) Write(buf []byte) (n int, err error)

Write 实现了 io.Writer 接口 参数:

• buf: 要写入的字节切片

返回值:

• n: 写入的字节数
• err: 错误信息

type ReadCloser

type ReadCloser interface {
	Reader
	io.Closer
}

ReadCloser 组合了 Reader 和 Closer 接口

func NewReader

func NewReader(r io.Reader) ReadCloser

NewReader 使用 msgio 帧读取器包装一个 io.Reader msgio.Reader 将一次读取完整的消息(使用长度) 假设另一端有等效的写入器 参数:

• r: 底层的 io.Reader

返回值:

• ReadCloser: 包装后的读取器

func NewReaderSize

func NewReaderSize(r io.Reader, maxMessageSize int) ReadCloser

NewReaderSize 与 NewReader 等效,但允许指定最大消息大小 参数:

• r: 底层的 io.Reader
• maxMessageSize: 最大消息大小

返回值:

• ReadCloser: 包装后的读取器

func NewReaderSizeWithPool

func NewReaderSizeWithPool(r io.Reader, maxMessageSize int, p *pool.BufferPool) ReadCloser

NewReaderSizeWithPool 与 NewReader 相同,但允许指定缓冲池和最大消息大小 参数:

• r: 底层的 io.Reader
• maxMessageSize: 最大消息大小
• p: 自定义的缓冲池

返回值:

• ReadCloser: 包装后的读取器

func NewReaderWithPool

func NewReaderWithPool(r io.Reader, p *pool.BufferPool) ReadCloser

NewReaderWithPool 与 NewReader 相同,但允许指定缓冲池 参数:

• r: 底层的 io.Reader
• p: 自定义的缓冲池

返回值:

• ReadCloser: 包装后的读取器

func NewVarintReader

func NewVarintReader(r io.Reader) ReadCloser

NewVarintReader 使用 varint msgio 帧读取器包装一个 io.Reader 读取器将一次读取完整的消息(使用长度) Varint 根据 https://golang.org/pkg/encoding/binary/#ReadUvarint 读取 假设另一端有等效的写入器 参数:

• r: 底层的 io.Reader

返回值:

• ReadCloser: 包装后的读取器

func NewVarintReaderSize

func NewVarintReaderSize(r io.Reader, maxMessageSize int) ReadCloser

NewVarintReaderSize 等同于 NewVarintReader，但允许指定最大消息大小 参数:

• r: 底层的 io.Reader
• maxMessageSize: 最大消息大小

返回值:

• ReadCloser: 包装后的读取器

func NewVarintReaderSizeWithPool

func NewVarintReaderSizeWithPool(r io.Reader, maxMessageSize int, p *pool.BufferPool) ReadCloser

NewVarintReaderSizeWithPool 与 NewVarintReader 相同，但允许指定缓冲池和最大消息大小 参数:

• r: 底层的 io.Reader
• maxMessageSize: 最大消息大小
• p: 缓冲池

返回值:

• ReadCloser: 包装后的读取器

func NewVarintReaderWithPool

func NewVarintReaderWithPool(r io.Reader, p *pool.BufferPool) ReadCloser

NewVarintReaderWithPool 与 NewVarintReader 相同，但允许指定缓冲池 参数:

• r: 底层的 io.Reader
• p: 缓冲池

返回值:

• ReadCloser: 包装后的读取器

type ReadWriteCloser

type ReadWriteCloser interface {
	Reader
	Writer
	io.Closer
}

ReadWriteCloser 组合了 Reader、Writer 和 Closer 接口

func Combine

func Combine(w Writer, r Reader) ReadWriteCloser

Combine 将一对 msgio.Writer 和 msgio.Reader 包装成 msgio.ReadWriter 参数:

• w: Writer 接口实现
• r: Reader 接口实现

返回值:

• ReadWriteCloser: 组合后的读写器

func NewReadWriter

func NewReadWriter(rw io.ReadWriter) ReadWriteCloser

NewReadWriter 使用 msgio.ReadWriter 包装一个 io.ReadWriter 写入和读取将被适当地加上帧 参数:

• rw: 底层的 io.ReadWriter

返回值:

• ReadWriteCloser: 包装后的读写器

type ReadWriter

type ReadWriter interface {
	Reader
	Writer
}

ReadWriter 组合了 Reader 和 Writer 接口

type Reader

type Reader interface {
	// Read 从 Reader 读取下一条消息
	// 客户端必须传入足够大的缓冲区,否则将返回 io.ErrShortBuffer
	// 参数:
	//   - []byte: 用于存储消息的缓冲区
	//
	// 返回值:
	//   - int: 读取的字节数
	//   - error: 错误信息
	Read([]byte) (int, error)

	// ReadMsg 从 Reader 读取下一条消息
	// 内部使用 pool.BufferPool 重用缓冲区
	// 用户可以调用 ReleaseMsg(msg) 来表示缓冲区可以被重用
	// 返回值:
	//   - []byte: 读取的消息内容
	//   - error: 错误信息
	ReadMsg() ([]byte, error)

	// ReleaseMsg 表示缓冲区可以被重用
	// 参数:
	//   - []byte: 要释放的消息缓冲区
	ReleaseMsg([]byte)

	// NextMsgLen 返回下一条(预览的)消息的长度
	// 不会破坏消息或产生其他副作用
	// 返回值:
	//   - int: 下一条消息的长度
	//   - error: 错误信息
	NextMsgLen() (int, error)
}

Reader 是 msgio Reader 接口,用于读取带长度前缀的消息

type WriteCloser

type WriteCloser interface {
	Writer
	io.Closer
}

WriteCloser 是 Writer + Closer 接口,类似于 golang/pkg/io

func NewVarintWriter

func NewVarintWriter(w io.Writer) WriteCloser

NewVarintWriter 使用 varint msgio 帧写入器包装一个 io.Writer 写入器将使用 https://golang.org/pkg/encoding/binary/#PutUvarint 将每个消息的长度前缀写为 varint 参数:

• w: 底层的 io.Writer

返回值:

• WriteCloser: 包装后的写入器

func NewVarintWriterWithPool

func NewVarintWriterWithPool(w io.Writer, p *pool.BufferPool) WriteCloser

NewVarintWriterWithPool 与 NewVarintWriter 相同，但允许指定缓冲池 参数:

• w: 底层的 io.Writer
• p: 缓冲池

返回值:

• WriteCloser: 包装后的写入器

func NewWriter

func NewWriter(w io.Writer) WriteCloser

NewWriter 使用 msgio 帧写入器包装一个 io.Writer msgio.Writer 将为每个写入的消息写入长度前缀 参数:

• w: 底层的 io.Writer

返回值:

• WriteCloser: 包装后的写入器

func NewWriterWithPool

func NewWriterWithPool(w io.Writer, p *pool.BufferPool) WriteCloser

NewWriterWithPool 与 NewWriter 相同,但允许用户传入自定义缓冲池 参数:

• w: 底层的 io.Writer
• p: 自定义的缓冲池

返回值:

• WriteCloser: 包装后的写入器

type Writer

type Writer interface {
	// Write 将传入的缓冲区作为单个消息写入
	// 参数:
	//   - []byte: 要写入的字节切片
	//
	// 返回值:
	//   - int: 写入的字节数
	//   - error: 错误信息
	Write([]byte) (int, error)

	// WriteMsg 将传入缓冲区中的消息写入
	// 参数:
	//   - []byte: 要写入的消息字节切片
	//
	// 返回值:
	//   - error: 错误信息
	WriteMsg([]byte) error
}

Writer 是 msgio Writer 接口,用于写入带长度前缀的消息