safemem

package
v0.0.0-...-0f8216c Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Dec 16, 2024 License: Apache-2.0, MIT Imports: 10 Imported by: 72

Documentation

Overview

Package safemem provides the Block and BlockSeq types.

Index

Constants

This section is empty.

Variables

View Source
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

func CompareAndSwapUint32(b Block, old, new uint32) (uint32, error)

CompareAndSwapUint32 invokes safecopy.CompareAndSwapUint32 on the first 4 bytes of b.

Preconditions: b.Len() >= 4.

func Copy

func Copy(dst, src Block) (int, error)

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

func CopySeq(dsts, srcs BlockSeq) (uint64, error)

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

func IovecsFromBlockSeq(bs BlockSeq) []unix.Iovec

IovecsFromBlockSeq returns a []unix.Iovec representing seq.

func LoadUint32

func LoadUint32(b Block) (uint32, error)

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

func SwapUint32(b Block, new uint32) (uint32, error)

SwapUint32 invokes safecopy.SwapUint32 on the first 4 bytes of b.

Preconditions: b.Len() >= 4.

func SwapUint64

func SwapUint64(b Block, new uint64) (uint64, error)

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.

func Zero

func Zero(dst Block) (int, error)

Zero sets all bytes in dst to 0 and returns the number of bytes zeroed.

func ZeroSeq

func ZeroSeq(dsts BlockSeq) (uint64, error)

ZeroSeq sets all bytes in dsts to 0 and returns the number of bytes zeroed.

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

func BlockFromSafePointer(ptr unsafe.Pointer, length int) Block

BlockFromSafePointer returns a Block equivalent to [ptr, ptr+length), which is safe to access without safecopy.

Preconditions: ptr+length does not overflow.

func BlockFromSafeSlice

func BlockFromSafeSlice(slice []byte) Block

BlockFromSafeSlice returns a Block equivalent to slice, which is safe to access without safecopy.

func BlockFromUnsafePointer

func BlockFromUnsafePointer(ptr unsafe.Pointer, length int) Block

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

func BlockFromUnsafeSlice(slice []byte) Block

BlockFromUnsafeSlice returns a Block equivalent to bs, which is not safe to access without safecopy.

func (Block) Addr

func (b Block) Addr() uintptr

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

func (b Block) DropFirst(n int) Block

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

func (b Block) DropFirst64(n uint64) Block

DropFirst64 is equivalent to DropFirst but takes a uint64.

func (Block) Len

func (b Block) Len() int

Len returns b's length in bytes.

func (Block) NeedSafecopy

func (b Block) NeedSafecopy() bool

NeedSafecopy returns true if accessing b.ToSlice() requires the use of safecopy.

func (Block) String

func (b Block) String() string

String implements fmt.Stringer.String.

func (Block) TakeFirst

func (b Block) TakeFirst(n int) Block

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

func (b Block) TakeFirst64(n uint64) Block

TakeFirst64 is equivalent to TakeFirst but takes a uint64.

func (Block) ToSlice

func (b Block) ToSlice() []byte

ToSlice returns a []byte equivalent to b.

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

func BlockSeqFromSlice(slice []Block) BlockSeq

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

func BlockSeqOf(b Block) BlockSeq

BlockSeqOf returns a BlockSeq representing the single Block b.

func (BlockSeq) DropFirst

func (bs BlockSeq) DropFirst(n int) BlockSeq

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

func (bs BlockSeq) DropFirst64(n uint64) BlockSeq

DropFirst64 is equivalent to DropFirst but takes an uint64.

func (BlockSeq) Head

func (bs BlockSeq) Head() Block

Head returns the first Block in bs.

Preconditions: !bs.IsEmpty().

func (BlockSeq) IsEmpty

func (bs BlockSeq) IsEmpty() bool

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) NumBlocks

func (bs BlockSeq) NumBlocks() int

NumBlocks returns the number of Blocks in bs.

func (BlockSeq) NumBytes

func (bs BlockSeq) NumBytes() uint64

NumBytes returns the sum of Block.Len() for all Blocks in bs.

func (BlockSeq) String

func (bs BlockSeq) String() string

String implements fmt.Stringer.String.

func (BlockSeq) Tail

func (bs BlockSeq) Tail() BlockSeq

Tail returns a BlockSeq consisting of all Blocks in bs after the first.

Preconditions: !bs.IsEmpty().

func (BlockSeq) TakeFirst

func (bs BlockSeq) TakeFirst(n int) BlockSeq

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

func (bs BlockSeq) TakeFirst64(n uint64) BlockSeq

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

type FromIOReader struct {
	Reader io.Reader
}

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

type FromIOWriter struct {
	Writer io.Writer
}

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

type FromVecReaderFunc struct {
	ReadVec func(dsts [][]byte) (int64, error)
}

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

type FromVecWriterFunc struct {
	WriteVec func(srcs [][]byte) (int64, error)
}

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

type ReaderFunc func(dsts BlockSeq) (uint64, error)

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.

func (ToIOReader) Read

func (r ToIOReader) Read(dst []byte) (int, error)

Read implements io.Reader.Read.

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

type WriterFunc func(srcs BlockSeq) (uint64, error)

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL