From e756222a7dde7800f4779f059c02cb8e404b102d Mon Sep 17 00:00:00 2001 From: Darien Raymond Date: Tue, 6 Dec 2016 17:17:07 +0100 Subject: [PATCH 1/4] comments --- common/alloc/buffer.go | 1 + 1 file changed, 1 insertion(+) diff --git a/common/alloc/buffer.go b/common/alloc/buffer.go index 9acb42c11..acf1e6e66 100644 --- a/common/alloc/buffer.go +++ b/common/alloc/buffer.go @@ -9,6 +9,7 @@ const ( defaultOffset = 16 ) +// A Writer that writes contents into the given buffer. type BytesWriter func([]byte) int // Buffer is a recyclable allocation of a byte array. Buffer.Release() recycles From 7a641749a8a93ad3b300b713f18248075e94b595 Mon Sep 17 00:00:00 2001 From: Darien Raymond Date: Tue, 6 Dec 2016 17:26:06 +0100 Subject: [PATCH 2/4] comments --- common/alloc/buffer.go | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/common/alloc/buffer.go b/common/alloc/buffer.go index acf1e6e66..8bbd4bb72 100644 --- a/common/alloc/buffer.go +++ b/common/alloc/buffer.go @@ -9,7 +9,7 @@ const ( defaultOffset = 16 ) -// A Writer that writes contents into the given buffer. +// BytesWriter is a writer that writes contents into the given buffer. type BytesWriter func([]byte) int // Buffer is a recyclable allocation of a byte array. Buffer.Release() recycles @@ -23,6 +23,7 @@ type Buffer struct { end int } +// CreateBuffer creates a new Buffer object based on given container and parent pool. func CreateBuffer(container []byte, parent Pool) *Buffer { b := new(Buffer) b.head = container @@ -68,6 +69,7 @@ func (b *Buffer) Append(data []byte) { b.end += nBytes } +// AppendFunc appends the content of a BytesWriter to the buffer. func (b *Buffer) AppendFunc(writer BytesWriter) { nBytes := writer(b.head[b.end:]) b.end += nBytes @@ -80,6 +82,7 @@ func (b *Buffer) Prepend(data []byte) { copy(b.head[b.start:], data) } +// PrependBytes prepends all data in front of the buffer. func (b *Buffer) PrependBytes(data ...byte) { b.Prepend(data) } @@ -89,10 +92,12 @@ func (b *Buffer) PrependFunc(offset int, writer BytesWriter) { writer(b.head[b.start:]) } +// Byte returns the bytes at index. func (b *Buffer) Byte(index int) byte { return b.head[b.start+index] } +// SetByte sets the byte value at index. func (b *Buffer) SetByte(index int, value byte) { b.head[b.start+index] = value } @@ -102,6 +107,7 @@ func (b *Buffer) Bytes() []byte { return b.head[b.start:b.end] } +// BytesRange returns a slice of this buffer with given from and to bounary. func (b *Buffer) BytesRange(from, to int) []byte { if from < 0 { from += b.Len() @@ -166,6 +172,7 @@ func (b *Buffer) Len() int { return b.end - b.start } +// IsEmpty returns true if the buffer is empty. func (b *Buffer) IsEmpty() bool { return b.Len() == 0 } @@ -217,10 +224,12 @@ func NewBuffer() *Buffer { return mediumPool.Allocate() } +// NewSmallBuffer returns a buffer with 2K bytes capacity. func NewSmallBuffer() *Buffer { return smallPool.Allocate() } +// NewLocalBuffer creates and returns a buffer on current thread. func NewLocalBuffer(size int) *Buffer { return CreateBuffer(make([]byte, size), nil) } From 5f6366d2fa0a5ca50425795bbd49731ee709ce16 Mon Sep 17 00:00:00 2001 From: Darien Raymond Date: Tue, 6 Dec 2016 17:26:51 +0100 Subject: [PATCH 3/4] comments --- common/alloc/buffer_pool.go | 1 + 1 file changed, 1 insertion(+) diff --git a/common/alloc/buffer_pool.go b/common/alloc/buffer_pool.go index 5d8ac0dd5..d8bc21dac 100644 --- a/common/alloc/buffer_pool.go +++ b/common/alloc/buffer_pool.go @@ -6,6 +6,7 @@ import ( "sync" ) +// Pool provides functionality to generate and recycle buffers on demand. type Pool interface { Allocate() *Buffer Free(*Buffer) From 36e4330e58958cf553346468664723c6c026ad1e Mon Sep 17 00:00:00 2001 From: Darien Raymond Date: Tue, 6 Dec 2016 17:36:28 +0100 Subject: [PATCH 4/4] comments --- common/alloc/buffer_pool.go | 6 ++++++ common/io/reader.go | 1 + common/io/transport.go | 3 +++ common/io/writer.go | 1 + 4 files changed, 11 insertions(+) diff --git a/common/alloc/buffer_pool.go b/common/alloc/buffer_pool.go index d8bc21dac..394d429b1 100644 --- a/common/alloc/buffer_pool.go +++ b/common/alloc/buffer_pool.go @@ -8,14 +8,18 @@ import ( // Pool provides functionality to generate and recycle buffers on demand. type Pool interface { + // Allocate either returns a unused buffer from the pool, or generates a new one from system. Allocate() *Buffer + // Free recycles the given buffer. Free(*Buffer) } +// SyncPool is a buffer pool based on sync.Pool type SyncPool struct { allocator *sync.Pool } +// NewSyncPool creates a SyncPool with given buffer size. func NewSyncPool(bufferSize uint32) *SyncPool { pool := &SyncPool{ allocator: &sync.Pool{ @@ -25,10 +29,12 @@ func NewSyncPool(bufferSize uint32) *SyncPool { return pool } +// Allocate implements Pool.Allocate(). func (p *SyncPool) Allocate() *Buffer { return CreateBuffer(p.allocator.Get().([]byte), p) } +// Free implements Pool.Free(). func (p *SyncPool) Free(buffer *Buffer) { rawBuffer := buffer.head if rawBuffer == nil { diff --git a/common/io/reader.go b/common/io/reader.go index 6554190f6..28e39bbc8 100644 --- a/common/io/reader.go +++ b/common/io/reader.go @@ -63,6 +63,7 @@ func (v *AdaptiveReader) Read() (*alloc.Buffer, error) { return buffer, nil } +// Release implements Releasable.Release(). func (v *AdaptiveReader) Release() { v.reader = nil } diff --git a/common/io/transport.go b/common/io/transport.go index 9bee868be..a56561a75 100644 --- a/common/io/transport.go +++ b/common/io/transport.go @@ -2,10 +2,12 @@ package io import ( "io" + "v2ray.com/core/common/errors" "v2ray.com/core/common/log" ) +// Pipe dumps all content from reader to writer, until an error happens. func Pipe(reader Reader, writer Writer) error { for { buffer, err := reader.Read() @@ -28,6 +30,7 @@ func Pipe(reader Reader, writer Writer) error { } } +// PipeUntilEOF behaves the same as Pipe(). The only difference is PipeUntilEOF returns nil on EOF. func PipeUntilEOF(reader Reader, writer Writer) error { err := Pipe(reader, writer) if err != nil && errors.Cause(err) != io.EOF { diff --git a/common/io/writer.go b/common/io/writer.go index 9d8a78e3d..cf255f6a6 100644 --- a/common/io/writer.go +++ b/common/io/writer.go @@ -39,6 +39,7 @@ func (v *AdaptiveWriter) Write(buffer *alloc.Buffer) error { return nil } +// Release implements Releasable.Release(). func (v *AdaptiveWriter) Release() { v.writer = nil }