safemem

package
v0.0.0-...-522126a Latest Latest
Warning

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

 Go to latest Published: Dec 23, 2019 License: Apache-2.0 Imports: 8 Imported by: 0

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 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 Reader, dsts BlockSeq) (uint64, error)

ReadFullToBlocks repeatedly invokes r.ReadToBlocks until dsts.NumBytes() bytes have been read or ReadToBlocks returns an error.

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 Writer, srcs BlockSeq) (uint64, error)

WriteFullFromBlocks repeatedly invokes w.WriteFromBlocks until srcs.NumBytes() bytes have been written or WriteFromBlocks returns an error.

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, len int) Block

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

Preconditions: ptr+len 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, len 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 FromIOReaderAt 

type FromIOReaderAt struct {
	ReaderAt io.ReaderAt
	Offset   int64
}

FromIOReaderAt implements Reader for an io.ReaderAt. Does not repeatedly invoke io.ReaderAt.ReadAt because ReadAt is more strict than Read. A partial read indicates an error. This is not thread-safe.

func (FromIOReaderAt) ReadToBlocks 

func (r FromIOReaderAt) 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 ToIOWriter 

type ToIOWriter struct {
	Writer Writer
}

ToIOWriter implements io.Writer for a (safemem.)Writer.

func (ToIOWriter) Write 

func (w ToIOWriter) Write(src []byte) (int, error)

Write implements io.Writer.Write.

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.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.