Documentation
¶
Overview ¶
Package safemem provides the Block and BlockSeq types.
Index ¶
- Variables
- func CompareAndSwapUint32(b Block, old, new uint32) (uint32, error)
- func Copy(dst, src Block) (int, error)
- func CopySeq(dsts, srcs BlockSeq) (uint64, error)
- func IovecsFromBlockSeq(bs BlockSeq) []unix.Iovec
- func LoadUint32(b Block) (uint32, error)
- func ReadFullToBlocks(r ReaderFunc, dsts BlockSeq) (uint64, error)
- func SwapUint32(b Block, new uint32) (uint32, error)
- func SwapUint64(b Block, new uint64) (uint64, error)
- func WriteFullFromBlocks(w WriterFunc, srcs BlockSeq) (uint64, error)
- func Zero(dst Block) (int, error)
- func ZeroSeq(dsts BlockSeq) (uint64, error)
- type Block
- func (b Block) Addr() uintptr
- func (b Block) DropFirst(n int) Block
- func (b Block) DropFirst64(n uint64) Block
- func (b Block) Len() int
- func (b Block) NeedSafecopy() bool
- func (b Block) String() string
- func (b Block) TakeFirst(n int) Block
- func (b Block) TakeFirst64(n uint64) Block
- func (b Block) ToSlice() []byte
- type BlockSeq
- func (bs BlockSeq) DropFirst(n int) BlockSeq
- func (bs BlockSeq) DropFirst64(n uint64) BlockSeq
- func (bs BlockSeq) Head() Block
- func (bs BlockSeq) IsEmpty() bool
- func (bs BlockSeq) NumBlocks() int
- func (bs BlockSeq) NumBytes() uint64
- func (bs BlockSeq) String() string
- func (bs BlockSeq) Tail() BlockSeq
- func (bs BlockSeq) TakeFirst(n int) BlockSeq
- func (bs BlockSeq) TakeFirst64(n uint64) BlockSeq
- type BlockSeqReader
- type BlockSeqWriter
- type FromIOReader
- type FromIOWriter
- type FromVecReaderFunc
- type FromVecWriterFunc
- type Reader
- type ReaderFunc
- type ToIOReader
- type Writer
- type WriterFunc
Constants ¶
This section is empty.
Variables ¶
var ErrEndOfBlockSeq = errors.New("write beyond end of BlockSeq")
ErrEndOfBlockSeq is returned by BlockSeqWriter when attempting to write beyond the end of the BlockSeq.
Functions ¶
func CompareAndSwapUint32 ¶
CompareAndSwapUint32 invokes safecopy.CompareAndSwapUint32 on the first 4 bytes of b.
Preconditions: b.Len() >= 4.
func Copy ¶
Copy copies src.Len() or dst.Len() bytes, whichever is less, from src to dst and returns the number of bytes copied.
If src and dst overlap, the data stored in dst is unspecified.
func CopySeq ¶
CopySeq copies srcs.NumBytes() or dsts.NumBytes() bytes, whichever is less, from srcs to dsts and returns the number of bytes copied.
If srcs and dsts overlap, the data stored in dsts is unspecified.
func IovecsFromBlockSeq ¶
IovecsFromBlockSeq returns a []unix.Iovec representing seq.
func LoadUint32 ¶
LoadUint32 invokes safecopy.LoadUint32 on the first 4 bytes of b.
Preconditions: b.Len() >= 4.
func ReadFullToBlocks ¶
func ReadFullToBlocks(r ReaderFunc, dsts BlockSeq) (uint64, error)
ReadFullToBlocks repeatedly invokes r until dsts.NumBytes() bytes have been read or r returns an error. Note that we avoid a Reader interface receiver to avoid heap allocation.
func SwapUint32 ¶
SwapUint32 invokes safecopy.SwapUint32 on the first 4 bytes of b.
Preconditions: b.Len() >= 4.
func SwapUint64 ¶
SwapUint64 invokes safecopy.SwapUint64 on the first 8 bytes of b.
Preconditions: b.Len() >= 8.
func WriteFullFromBlocks ¶
func WriteFullFromBlocks(w WriterFunc, srcs BlockSeq) (uint64, error)
WriteFullFromBlocks repeatedly invokes w until srcs.NumBytes() bytes have been written or w returns an error. Note that we avoid a Writer interface receiver to avoid heap allocation.
Types ¶
type Block ¶
type Block struct {
// contains filtered or unexported fields
}
A Block is a range of contiguous bytes, similar to []byte but with the following differences:
The memory represented by a Block may require the use of safecopy to access.
Block does not carry a capacity and cannot be expanded.
Blocks are immutable and may be copied by value. The zero value of Block represents an empty range, analogous to a nil []byte.
func BlockFromSafePointer ¶
BlockFromSafePointer returns a Block equivalent to [ptr, ptr+length), which is safe to access without safecopy.
Preconditions: ptr+length does not overflow.
func BlockFromSafeSlice ¶
BlockFromSafeSlice returns a Block equivalent to slice, which is safe to access without safecopy.
func BlockFromUnsafePointer ¶
BlockFromUnsafePointer returns a Block equivalent to [ptr, ptr+len), which is not safe to access without safecopy.
Preconditions: ptr+len does not overflow.
func BlockFromUnsafeSlice ¶
BlockFromUnsafeSlice returns a Block equivalent to bs, which is not safe to access without safecopy.
func (Block) Addr ¶
Addr returns b's start address as a uintptr. It returns uintptr instead of unsafe.Pointer so that code using safemem cannot obtain unsafe.Pointers without importing the unsafe package explicitly.
Note that a uintptr is not recognized as a pointer by the garbage collector, such that if there are no uses of b after a call to b.Addr() and the address is to Go-managed memory, the returned uintptr does not prevent garbage collection of the pointee.
func (Block) DropFirst ¶
DropFirst returns a Block equivalent to b, but with the first n bytes omitted. It is analogous to the [n:] operation on a slice, except that if n > b.Len(), DropFirst returns an empty Block instead of panicking.
Preconditions: n >= 0.
func (Block) DropFirst64 ¶
DropFirst64 is equivalent to DropFirst but takes a uint64.
func (Block) NeedSafecopy ¶
NeedSafecopy returns true if accessing b.ToSlice() requires the use of safecopy.
func (Block) TakeFirst ¶
TakeFirst returns a Block equivalent to the first n bytes of b. It is analogous to the [:n] operation on a slice, except that if n > b.Len(), TakeFirst returns a copy of b instead of panicking.
Preconditions: n >= 0.
func (Block) TakeFirst64 ¶
TakeFirst64 is equivalent to TakeFirst but takes a uint64.
type BlockSeq ¶
type BlockSeq struct {
// contains filtered or unexported fields
}
A BlockSeq represents a sequence of Blocks, each of which has non-zero length.
BlockSeqs are immutable and may be copied by value. The zero value of BlockSeq represents an empty sequence.
func BlockSeqFromSlice ¶
BlockSeqFromSlice returns a BlockSeq representing all Blocks in slice. If slice contains Blocks with zero length, BlockSeq will skip them during iteration.
Whether the returned BlockSeq shares memory with slice is unspecified; clients should avoid mutating slices passed to BlockSeqFromSlice.
Preconditions: The combined length of all Blocks in slice <= math.MaxUint64.
func BlockSeqOf ¶
BlockSeqOf returns a BlockSeq representing the single Block b.
func (BlockSeq) DropFirst ¶
DropFirst returns a BlockSeq equivalent to bs, but with the first n bytes omitted. If n > bs.NumBytes(), DropFirst returns an empty BlockSeq.
Preconditions: n >= 0.
func (BlockSeq) DropFirst64 ¶
DropFirst64 is equivalent to DropFirst but takes an uint64.
func (BlockSeq) IsEmpty ¶
IsEmpty returns true if bs contains no Blocks.
Invariants: bs.IsEmpty() == (bs.NumBlocks() == 0) == (bs.NumBytes() == 0). (Of these, prefer to use bs.IsEmpty().)
func (BlockSeq) Tail ¶
Tail returns a BlockSeq consisting of all Blocks in bs after the first.
Preconditions: !bs.IsEmpty().
func (BlockSeq) TakeFirst ¶
TakeFirst returns a BlockSeq equivalent to the first n bytes of bs. If n > bs.NumBytes(), TakeFirst returns a BlockSeq equivalent to bs.
Preconditions: n >= 0.
func (BlockSeq) TakeFirst64 ¶
TakeFirst64 is equivalent to TakeFirst but takes a uint64.
type BlockSeqReader ¶
type BlockSeqReader struct {
Blocks BlockSeq
}
BlockSeqReader implements Reader by reading from a BlockSeq.
func (*BlockSeqReader) ReadToBlocks ¶
func (r *BlockSeqReader) ReadToBlocks(dsts BlockSeq) (uint64, error)
ReadToBlocks implements Reader.ReadToBlocks.
type BlockSeqWriter ¶
type BlockSeqWriter struct {
Blocks BlockSeq
}
BlockSeqWriter implements Writer by writing to a BlockSeq.
func (*BlockSeqWriter) WriteFromBlocks ¶
func (w *BlockSeqWriter) WriteFromBlocks(srcs BlockSeq) (uint64, error)
WriteFromBlocks implements Writer.WriteFromBlocks.
type FromIOReader ¶
FromIOReader implements Reader for an io.Reader by repeatedly invoking io.Reader.Read until it returns an error or partial read. This is not thread-safe.
FromIOReader will return a successful partial read iff Reader.Read does so.
func (FromIOReader) ReadToBlocks ¶
func (r FromIOReader) ReadToBlocks(dsts BlockSeq) (uint64, error)
ReadToBlocks implements Reader.ReadToBlocks.
type FromIOWriter ¶
FromIOWriter implements Writer for an io.Writer by repeatedly invoking io.Writer.Write until it returns an error or partial write.
FromIOWriter will tolerate implementations of io.Writer.Write that return partial writes with a nil error in contravention of io.Writer's requirements, since Writer is permitted to do so. FromIOWriter will return a successful partial write iff Writer.Write does so.
func (FromIOWriter) WriteFromBlocks ¶
func (w FromIOWriter) WriteFromBlocks(srcs BlockSeq) (uint64, error)
WriteFromBlocks implements Writer.WriteFromBlocks.
type FromVecReaderFunc ¶
FromVecReaderFunc implements Reader for a function that reads data into a [][]byte and returns the number of bytes read as an int64.
func (FromVecReaderFunc) ReadToBlocks ¶
func (r FromVecReaderFunc) ReadToBlocks(dsts BlockSeq) (uint64, error)
ReadToBlocks implements Reader.ReadToBlocks.
ReadToBlocks calls r.ReadVec at most once.
type FromVecWriterFunc ¶
FromVecWriterFunc implements Writer for a function that writes data from a [][]byte and returns the number of bytes written.
func (FromVecWriterFunc) WriteFromBlocks ¶
func (w FromVecWriterFunc) WriteFromBlocks(srcs BlockSeq) (uint64, error)
WriteFromBlocks implements Writer.WriteFromBlocks.
WriteFromBlocks calls w.WriteVec at most once.
type Reader ¶
type Reader interface {
// ReadToBlocks reads up to dsts.NumBytes() bytes into dsts and returns the
// number of bytes read. It may return a partial read without an error
// (i.e. (n, nil) where 0 < n < dsts.NumBytes()). It should not return a
// full read with an error (i.e. (dsts.NumBytes(), err) where err != nil);
// note that this differs from io.Reader.Read (in particular, io.EOF should
// not be returned if ReadToBlocks successfully reads dsts.NumBytes()
// bytes.)
ReadToBlocks(dsts BlockSeq) (uint64, error)
}
Reader represents a streaming byte source like io.Reader.
type ReaderFunc ¶
ReaderFunc implements Reader for a function with the semantics of Reader.ReadToBlocks.
func (ReaderFunc) ReadToBlocks ¶
func (f ReaderFunc) ReadToBlocks(dsts BlockSeq) (uint64, error)
ReadToBlocks implements Reader.ReadToBlocks.
type ToIOReader ¶
type ToIOReader struct {
Reader Reader
}
ToIOReader implements io.Reader for a (safemem.)Reader.
ToIOReader will return a successful partial read iff Reader.ReadToBlocks does so.
type Writer ¶
type Writer interface {
// WriteFromBlocks writes up to srcs.NumBytes() bytes from srcs and returns
// the number of bytes written. It may return a partial write without an
// error (i.e. (n, nil) where 0 < n < srcs.NumBytes()). It should not
// return a full write with an error (i.e. srcs.NumBytes(), err) where err
// != nil).
WriteFromBlocks(srcs BlockSeq) (uint64, error)
}
Writer represents a streaming byte sink like io.Writer.
type WriterFunc ¶
WriterFunc implements Writer for a function with the semantics of Writer.WriteFromBlocks.
func (WriterFunc) WriteFromBlocks ¶
func (f WriterFunc) WriteFromBlocks(srcs BlockSeq) (uint64, error)
WriteFromBlocks implements Writer.WriteFromBlocks.
Source Files