Documentation
¶
Overview ¶
Package putback provides a net.Conn wrapper with a byte buffer that can be prepended to the connection's unread input.
A Conn is useful when code must inspect bytes and later present the same byte stream to another consumer. PutBack copies its argument and prepends it to the unread stream. Bytes within one PutBack call retain their order. Across calls, the most recent call is read first:
c.PutBack([]byte("one"))
c.PutBack([]byte("two"))
// Subsequent reads produce "twoone" before underlying bytes.
This stack-like ordering is intentional. If a caller reads a prefix while older put-back bytes remain, putting that prefix back must place it before the remaining bytes to reconstruct the original stream.
Conn preserves byte order, but it cannot preserve read chunk boundaries, concrete connection identity, or the exact time at which an underlying read error was reported. New takes a bufpool.Pool for copied put-back buffers. If the pool argument is nil, each put-back copy is allocated with make. New returns nil if the connection argument is nil.
The pool is only used for internal copies made by PutBack. Conn never stores or returns caller-owned slices. A pooled put-back buffer is returned to the pool when its bytes are fully read, when a later PutBack replaces it with a combined buffer, when TCPConn.WriteTo fully writes it, or when PostClose releases it. After a buffer is returned to the pool, Conn does not read from it or write to it again. Partially read or partially written put-back buffers stay owned by Conn until the remaining bytes are consumed, replaced, or released by PostClose.
If New receives a gonnect.TCPConn, the returned value also implements TCPConn and gonnect.TCPConn. If the TCP connection has standard library socket methods such as File, SyscallConn, SetReadBuffer, SetWriteBuffer, or MultipathTCP, those methods are preserved and delegate to the wrapped connection. Raw socket methods operate on the wrapped connection and do not include bytes held in the put-back buffer.
If an underlying Read returns both bytes and an error, Conn returns the bytes first and defers the error to the next Read. This normalization makes byte replay reliable and follows the io.Reader requirement to process bytes before an accompanying error.
Conn is not safe for concurrent read-side operations. Do not call Read, PutBack, Buffered, or PostClose concurrently with each other. For TCPConn, WriteTo is also a read-side operation. PreClose can be called while reads or writes are active. Like a normal net.Conn, Conn can still be used concurrently by one goroutine that reads and one goroutine that writes, subject to the underlying connection's guarantees. Writes, address queries, and deadline methods are delegated directly to the underlying connection. Close is equivalent to PostClose, which first runs PreClose if needed.
Buffered reads do not call the underlying connection, so an underlying read deadline is not consulted until the put-back buffer has been drained.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Conn ¶
type Conn interface {
net.Conn
gonnect.TwoStepCloser
// PutBack copies p and prepends it to the unread byte stream.
//
// Bytes within p retain their order. If PutBack is called more than once,
// bytes from the most recent call are read first. For example, putting back
// "one" and then "two" causes subsequent reads to produce "twoone" before any
// bytes obtained from the underlying connection.
//
// PutBack with an empty slice has no effect.
//
// PutBack is not safe for concurrent use with Read, Buffered, or another
// PutBack call.
PutBack(p []byte)
// Buffered reports the number of bytes currently waiting in the put-back
// buffer. It does not include bytes waiting in the operating system or a
// deferred read error.
//
// Buffered is not safe for concurrent use with Read or PutBack.
Buffered() int
GetWrapped() any
}
Conn wraps a net.Conn and allows bytes to be prepended to its unread input.
Conn is not safe for concurrent read-side operations. Do not call Read, PutBack, Buffered, or PostClose concurrently with each other. Like a normal net.Conn, Conn can still be used concurrently by one goroutine that reads and one goroutine that writes, subject to the underlying connection's guarantees. PreClose can be called while reads or writes are active. For TCPConn, WriteTo is also a read-side operation.
func New ¶
New wraps nc and uses pool to allocate copied put-back buffers. If pool is nil, each put-back copy is allocated with make. Pooled buffers are returned when buffered bytes are drained, replaced by a later PutBack, written by TCPConn.WriteTo, or released by PostClose.
If nc implements gonnect.TCPConn, the returned value also implements TCPConn and gonnect.TCPConn.
New returns nil if nc is nil.
Source Files