Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Algorithm ¶
type Algorithm uint32
Algorithm identifies which defragmentation algorithm will be used for defrag passes
const ( // AlgorithmFast indicates that the defragmentation run should use a "fast" // algorithm that is less thorough about compacting data within blocks, but requires fewer passes // to complete a full run. AlgorithmFast Algorithm = iota + 1 // AlgorithmFull indicates that the defragmentation run should use an algorithm // that is somewhat slower than DefragmentationFlagAlgorithmFast but will compact memory within blocks, // allowing subsequent passes to compact memory across blocks to use the space that was just freed up. // // This is the default algorithm if none is specified. AlgorithmFull )
type BlockList ¶
type BlockList[T any] interface { // MetadataForBlock retrieves the metadata.BlockMetadata corresponding to the memory page identified by // the provided index MetadataForBlock(index int) metadata.BlockMetadata // BlockCount retrieves the number of memory pages in the BlockList BlockCount() int // AddStatistics accumulates basic statistics about how many blocks, bytes, etc. are in the BlockList // and adds them to a memutils.Statistics object AddStatistics(stats *memutils.Statistics) // MoveDataForUserData retrieves a MoveAllocationData with data prepopulated (except for Move.DstTmpAllocation) // based on a userData object retrieved from metadata.BlockMetadata MoveDataForUserData(userData any) MoveAllocationData[T] // BufferImageGranularity retrieves the BufferImageGranularity that is used to assign offsets for this // BlockList object BufferImageGranularity() int // Lock locks the BlockList so that the internal slice of blocks can be modified Lock() // Unlock releases the lock taken by Lock Unlock() // CreateAlloc generates a new allocation of the type used internally to the BlockList, to be used // as DstTmpAllocation in a MoveAllocationData object CreateAlloc() *T // CommitDefragAllocationRequest allocates real memory in the BlockList as part of a relocation oepration // // allocRequest - a new metadata.AllocationRequest indicating the properties of the allocation to apply, generated // internally by metadata.BlockMetadata // // blockIndex - The index of the memory page to allocate to // // alignment - The alignment of the new memory offset being chosen // // flags - The intended behavior of the new allocation // // userData - A sentinel value used internally by the defragmentation system to be assigned as userData to the allocation // // subAllocType - The type used for the new allocation // // outAlloc - An allocation object of the type used internally to the BlockList, to which the allocation will be assigned CommitDefragAllocationRequest(allocRequest metadata.AllocationRequest, blockIndex int, alignment uint, flags uint32, userData any, suballocType uint32, outAlloc *T) (common.VkResult, error) // SwapBlocks rearranges memory pages within the BlockList's internal slice. The defragmentation code will handle calling Lock / Unlock // so it is not necessary for this method to be thread safe. SwapBlocks(leftIndex, rightIndex int) }
BlockList is an interface that is used to indicate a single block-bearing memory pool from a consuming application. The defragmentation code uses this to communicate back to a memory pool that holds the allocations being relocated in the code calling into the defragmentation process.
Semantically, it is expected that a BlockList represent several pages of memory, identified by index, and each page has several allocations of type T that point into various offsets in the memory page.
The memory page is represented within memutils by metadata.BlockMetadata, which tracks where the offsets of free and allocated memory are.
If you are attempting to use memutils to implement a new type of memory manager with defragmentation, you will need a memory pool object to implement this interface.
type DefragmentOperationHandler ¶
type DefragmentOperationHandler[T any] func(move DefragmentationMove[T]) error
DefragmentOperationHandler is a callback type that is used to allow consumers to be notified that it is time to follow through on the operation identified by DefragmentationMove.MoveOperation
type DefragmentationMove ¶
type DefragmentationMove[T any] struct { MoveOperation DefragmentationMoveOperation Size int SrcBlockMetadata metadata.BlockMetadata SrcAllocation *T DstBlockMetadata metadata.BlockMetadata DstTmpAllocation *T }
DefragmentationMove represents a single relocation operation being proposed by the defragmentation code. Within is a Size indicating the total number of bytes to relocate, a source and destination allocation, and a MoveOperation that initially defaults to DefragmentationMoveCopy but can be changed by the consumer if other operations are more appropriate).
type DefragmentationMoveOperation ¶
type DefragmentationMoveOperation uint32
DefragmentationMoveOperation is an enum that identifies what type of move operation to perform on a DefragmentationMove
const ( DefragmentationMoveCopy DefragmentationMoveOperation = iota DefragmentationMoveIgnore DefragmentationMoveDestroy )
type DefragmentationStats ¶
type DefragmentationStats struct {
// BytesMoved is the number of bytes that have been successfully relocated
BytesMoved int
// BytesFreed is the number of bytes that have been freed: bear in mind that relocating an allocation doesn't necessarily
// free its memory- only if the defragmentation run completely frees up a block of memory and the
// BlockList chooses to free it will this value increase
BytesFreed int
// AllocationsMoved is the number of successful relocations
AllocationsMoved int
// DeviceMemoryBlocksFreed is the number of memory pages that the BlockList has chosen to free as a consequence
// of relocating allocations out of the block
DeviceMemoryBlocksFreed int
}
DefragmentationStats contains basic metrics for defragmentation over time
func (*DefragmentationStats) Add ¶
func (s *DefragmentationStats) Add(stats DefragmentationStats)
type MetadataDefragContext ¶
type MetadataDefragContext[T any] struct { // Algorithm is the defragmentation algorithm that should be used Algorithm Algorithm // Handler is a method that will be called to complete each relocation as part of BlockListCompletePass Handler DefragmentOperationHandler[T] // BlockList is the memory object this context exists to defragment BlockList BlockList[T] // contains filtered or unexported fields }
MetadataDefragContext is the core of the defragmentation logic for memutils. One of these must be created and initialized for each defragmentation run, which will then consist of multiple passes
func (*MetadataDefragContext[T]) BlockListCollectMoves ¶
func (c *MetadataDefragContext[T]) BlockListCollectMoves(pass *PassContext) bool
BlockListCollectMoves will retrieve a single pass's worth of DefragmentationMove operations to be completed. Those operations can be retrieved from MetadataDefragContext.Moves.
stateIndex - the index of blockList within the larger set of BlockList objects being defragmented in this run
blockList - the memory pool to collect relocation operations for
func (*MetadataDefragContext[T]) BlockListCompletePass ¶
func (c *MetadataDefragContext[T]) BlockListCompletePass(pass *PassContext) error
BlockListCompletePass should be called after a defragmentation pass has been worked: BlockListCollectMoves have been called, we have copied data over for all relocation operations found, and the set of DefragmentationMove operations have had their operation type changed away from DefragmentationMoveCopy if necessary.
This method will clean up the pass by incrementing DefragmentationStats, calling MetadataDefragContext.Handler for each operation, and reorganizing free blocks within the BlockList if necessary. This method will return any errors returned from MetadataDefragContext.Handler as a combined error with errors.Join. It will also return a boolean- false if there is more defragmentation work to perform, true if the run is now complete.
stateIndex - the index of blockList within the list of all blockLists being defragmented
blockList - The memory pool to complete defragmentation of
func (*MetadataDefragContext[T]) Init ¶
func (c *MetadataDefragContext[T]) Init() error
Init sets up this MetadataDefragContext to be used in a fresh defragmentation run. MetadataDefragContext can be reused for multiple runs, as long as this method is called prior to beginning each run, including the first
func (*MetadataDefragContext[T]) Moves ¶
func (c *MetadataDefragContext[T]) Moves() []DefragmentationMove[T]
Moves returns the list of relocation operations most recently collected with BlockListCollectMoves
type MoveAllocationData ¶
type MoveAllocationData[T any] struct { Alignment uint SuballocationType uint32 Flags uint32 Move DefragmentationMove[T] }
MoveAllocationData represents a single allocation that needs to be relocated. It contains useful information about the moving allocation, as well as a DefragmentationMove object that is generally populated with source allocation information, but not destination allocation yet. This object will be used to allocate the DefragmentationMove.DstTmpAllocation object
type PassContext ¶
type PassContext struct {
// MaxPassBytes is the maximum number of bytes to relocate in each pass. There is no guarantee that
// this many bytes will actually be relocated in any given pass, based on how easy it is to find additional
// relocations to fit within the budget
MaxPassBytes int
// MaxPassAllocations is the maximum number of relocations to perform in each pass. There is no guarantee
// that this many allocations will actually be relocated in any given pass, based on how easy it is to find
// additional relocations to fit within the budget. This value is a close proxy for the number of go allocations
// made for each pass, so managing this and MaxPassBytes can help you control memory and cpu throughput of the
// defragmentation process.
MaxPassAllocations int
Stats DefragmentationStats
// contains filtered or unexported fields
}
Source Files