Documentation
¶
Overview ¶
Package memory provides support for allocating and reusing contiguous [Region]s of memory.
An Allocator supports reclaiming memory regions for reuse, invaliding existing regions. Using a memory region after it has been reclaimed produces undefined behavior, so caution must be taken to ensure that the lifetime of Memory does not exceed the lifetime of the owning Allocator.
Utility packages are provided to make it easier to work with memory regions:
- github.com/grafana/loki/v3/pkg/memory/buffer for resizable typed buffers.
- github.com/grafana/loki/v3/pkg/memory/bitmap for bitmaps.
Memory is EXPERIMENTAL and is currently only intended for use by github.com/grafana/loki/v3/pkg/dataobj.
Index ¶
- type Allocator
- type Bitmap
- func (bmap *Bitmap) Append(value bool)
- func (bmap *Bitmap) AppendBitmap(from Bitmap)
- func (bmap *Bitmap) AppendCount(value bool, count int)
- func (bmap *Bitmap) AppendCountUnsafe(value bool, count int)
- func (bmap *Bitmap) AppendUnsafe(value bool)
- func (bmap *Bitmap) AppendValues(values ...bool)
- func (bmap *Bitmap) Bytes() (data []byte, offset int)
- func (bmap *Bitmap) Cap() int
- func (bmap *Bitmap) ClearCount() int
- func (bmap *Bitmap) Clone(alloc *Allocator) *Bitmap
- func (bmap *Bitmap) Get(i int) bool
- func (bmap *Bitmap) Grow(n int)
- func (bmap *Bitmap) IterValues(value bool) iter.Seq[int]
- func (bmap *Bitmap) Len() int
- func (bmap *Bitmap) Resize(n int)
- func (bmap *Bitmap) Set(i int, value bool)
- func (bmap *Bitmap) SetCount() int
- func (bmap *Bitmap) SetRange(from, to int, value bool)
- func (bmap *Bitmap) Slice(i, j int) *Bitmap
- type Buffer
- func (buf *Buffer[T]) Append(values ...T)
- func (buf *Buffer[T]) AppendCount(value T, n int)
- func (buf *Buffer[T]) Cap() int
- func (buf *Buffer[T]) Clear()
- func (buf *Buffer[T]) Data() []T
- func (buf *Buffer[T]) Get(i int) T
- func (buf *Buffer[T]) Grow(n int)
- func (buf *Buffer[T]) Len() int
- func (buf *Buffer[T]) Push(value T)
- func (buf *Buffer[T]) Resize(n int)
- func (buf *Buffer[T]) Serialize() []byte
- func (buf *Buffer[T]) Set(i int, value T)
- func (buf *Buffer[T]) Slice(i, j int) *Buffer[T]
- type Region
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Allocator ¶
type Allocator struct {
// contains filtered or unexported fields
}
Allocator is an arena-style memory allocator that manages a set of memory regions.
An Allocator must not be copied after first use.
The Allocator can be reset to reclaim memory regions, marking them as free for future calls to Allocator.Allocate.
Allocator is unsafe and provides no use-after-free checks for Region. Callers must take care to ensure that the lifetime of a returned Memory does not exceed the lifetime of an allocator reuse cycle.
Allocators are not goroutine safe. If an Allocator methods are called concurrently, the method will panic.
func NewAllocator ¶
NewAllocator creates a new Allocator with the given parent. If parent is nil, the returned allocator is a root allocator.
Child allocators will obtain memory from their parent and can manage its own Trim and Reclaim lifecycle. All memory allocated from a child is invalidated when any of its parents (up to the root) reclaims memory.
func (*Allocator) Allocate ¶
Allocate retrieves the next free Memory region that can hold at least size bytes. If there is no such free Memory region, a new memory region will be created.
func (*Allocator) AllocatedBytes ¶
AllocatedBytes returns the total amount of bytes owned by the Allocator.
func (*Allocator) Free ¶
func (alloc *Allocator) Free()
Free returns all memory regions back to the parent allocator, if there is one. Otherwise, released memory regions are returned to the Go runtime for garbage collection.
It is a convenience wrapper for calling Allocator.Reclaim and Allocator.Trim (in that order).
func (*Allocator) FreeBytes ¶
FreeBytes returns the total amount of bytes available for Memory to use without requiring additional allocations.
func (*Allocator) Reclaim ¶
func (alloc *Allocator) Reclaim()
Reclaim all memory regions back to the Allocator for reuse. After calling Reclaim, any Region returned by the Allocator or any child allocators must no longer be used.
func (*Allocator) Reset ¶
func (alloc *Allocator) Reset()
Reset resets the Allocator for reuse. It is a convenience wrapper for calling Allocator.Trim and Allocator.Reclaim (in that order).
Advanced use cases may wish to selectively call Trim depending on the values of Allocator.AllocatedBytes and Allocator.FreeBytes.
func (*Allocator) Trim ¶
func (alloc *Allocator) Trim()
Trim releases unused memory regions. If the allocator has a parent, released memory regions are returned to the parent allocator. Otherwise, released memory regions may be returned to the Go runtime for garbage collection.
If Trim is called after Reclaim, all memory regions will be released.
type Bitmap ¶
type Bitmap struct {
// contains filtered or unexported fields
}
Bitmap is a bit-packed representation of a sequence of boolean values. Bits are ordered in LSB (Least Significant Bit) for compatibility with Apache Arrow.
The zero value is ready for use, unassociated with a memory allocator. Use NewBitmap to create an allocator-associated bitmap.
func NewBitmap ¶
NewBitmap creates a Bitmap managed by the provided allocator. The returned Bitmap will have an initial length of zero and a capacity of at least n (which may be 0).
If alloc is nil, memory is created using Go's built-in memory allocation. Otherwise, the lifetime of the returned Bitmap must not exceed the lifetime of alloc.
func (*Bitmap) AppendBitmap ¶
AppendBitmap appends the contents of another bitmap into bmap.
func (*Bitmap) AppendCount ¶
AppendCount appends value count times to bmap.
func (*Bitmap) AppendCountUnsafe ¶
AppendCountUnsafe appends value count times to bmap without checking for capacity.
func (*Bitmap) AppendUnsafe ¶
AppendUnsafe appends value to bmap without checking for capacity.
func (*Bitmap) AppendValues ¶
AppendValues adds a sequence of values to bmap.
func (*Bitmap) Bytes ¶
Bytes returns the raw representation of bmap, with bits stored in Least Significant Bit (LSB) order.
The offset return parameter denotes the offset of the first bit in data. This can be set to non-zero if bmap is sliced partially into a word.
The first offset bits in data are undefined.
func (*Bitmap) ClearCount ¶
ClearCount returns the number of bits unset in the bitmap.
func (*Bitmap) Clone ¶
Clone returns a copy of bmap using the provided allocator. The returned bitmap will store the provided allocator for future allocations.
If bmap is an unaligned slice, the cloned bitmap will be normalized to remove offsets. See Bitmap.Bytes for more information on aligned slices.
func (*Bitmap) Grow ¶
Grow increases bmap's capacity, if necessary, to guarantee space for another n values. After Grow(n), at least n values can be appended to bmap without another allocation. If n is negative or too large to allocate the memory, Grow panics.
func (*Bitmap) IterValues ¶
IterValues returns an iterator over bits, returning the index of each bit matching value.
func (*Bitmap) Resize ¶
Resize changes the length of bmap to n, allowing to set any index of bmap up to n. Resize will allocate additional memory if necessary.
func (*Bitmap) Set ¶
Set sets the bit at index i to the given value. Set panics if i is out of range of the length.
func (*Bitmap) SetRange ¶
SetRange sets all the bits in the range [from, to). SetRange panics if from > to or if to > bmap.Len().
type Buffer ¶
type Buffer[T any] struct { // contains filtered or unexported fields }
Buffer is a low-level memory buffer for storing a set of elements contiguously in memory.
Buffers must be created using NewBuffer.
func NewBuffer ¶
NewBuffer creates a Buffer managed by the provided allocator. The returned Buffer will have an initial length of zero and a capacity of at least n (which may be 0).
The lifetime of the returned Buffer must not exceed the lifetime of alloc.
func (*Buffer[T]) Append ¶
func (buf *Buffer[T]) Append(values ...T)
Append appends a set of values to buf, adding len(values) to buf's length. Append panics if there is not enough capacity for at least len(values) to be pushed.
func (*Buffer[T]) AppendCount ¶
AppendCount appends the value to buf n times, adding n to buf's length. AppendCount panics if there is not enough capacity for the value to be appended n times.
func (*Buffer[T]) Data ¶
func (buf *Buffer[T]) Data() []T
Data returns the current data slice of buf so that elements can be read or modified directly.
func (*Buffer[T]) Grow ¶
Grow increases the capacity of buf, if necessary, to have space for at least another n elements. After Grow(n), at least n elements can be pushed to the slice without another allocation. If n is negative or too large to allocate the memory, Grow panics.
func (*Buffer[T]) Push ¶
func (buf *Buffer[T]) Push(value T)
Push appends a single value to buf, adding 1 to buf's length. Push panics if there is not enough capacity for the value to be pushed.
func (*Buffer[T]) Resize ¶
Resize changes the length of buf to n, allowing to call Buffer.Set on any index up to n. Resize panics if n is bigger than the capacity of the buffer.
func (*Buffer[T]) Serialize ¶
Serialize returns the serializable form of the underlying byte array representing buf, padded to 64-bytes. Padded bytes will be set to zero.
The returned memory is shared with buf, not a copy.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
internal
|
|
|
memalign
Package memalign provides utilities for aligning memory.
|
Package memalign provides utilities for aligning memory. |
|
unsafecast
Package unsafecast provides utilties for performing unsafe type casts.
|
Package unsafecast provides utilties for performing unsafe type casts. |