Merge branch 'master' of https://github.com/v2ray/v2ray-core

common/alloc/buffer.go

@@ -9,6 +9,7 @@ const (
 	defaultOffset = 16
 )
 
+// 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
@@ -22,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.v = container
@@ -67,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.v[b.end:])
 	b.end += nBytes
@@ -79,6 +82,7 @@ func (b *Buffer) Prepend(data []byte) {
 	copy(b.v[b.start:], data)
 }
 
+// PrependBytes prepends all data in front of the buffer.
 func (b *Buffer) PrependBytes(data ...byte) {
 	b.Prepend(data)
 }
@@ -88,10 +92,12 @@ func (b *Buffer) PrependFunc(offset int, writer BytesWriter) {
 	writer(b.v[b.start:])
 }
 
+// Byte returns the bytes at index.
 func (b *Buffer) Byte(index int) byte {
 	return b.v[b.start+index]
 }
 
+// SetByte sets the byte value at index.
 func (b *Buffer) SetByte(index int, value byte) {
 	b.v[b.start+index] = value
 }
@@ -105,6 +111,7 @@ func (b *Buffer) SetBytesFunc(writer BytesWriter) {
 	b.end = b.start + writer(b.v[b.start:])
 }
 
+// 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()
@@ -169,6 +176,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
 }
@@ -220,10 +228,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)
 }

common/alloc/buffer_pool.go

@@ -6,15 +6,20 @@ import (
 	"sync"
 )
 
+// 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{
@@ -24,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.v
 	if rawBuffer == nil {

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
 }

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 {

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
 }