mappedresource

type AcquireOptions ¶

type AcquireOptions struct {
	Reason         string
	ValidationMode ValidationMode
	PreferMapped   bool
	AllowHeapCopy  bool
	FallbackReason FallbackReason
	ResourceRoot   string
	ResourcePath   string
}

AcquireOptions controls resource acquisition and accounting labels. ResourceRoot and ResourcePath identify the durable storage root/path for maintenance filtering when the handle protects file-backed resources.

type Class ¶

type Class string

Class identifies the resource family. It is coarse enough for shared accounting but does not replace subsystem-specific formats.

const (
	ClassValueLog         Class = "value_log"
	ClassLeafLog          Class = "leaf_log"
	ClassTypedRowAsset    Class = "typed_row_asset"
	ClassTypedColumnAsset Class = "typed_column_asset"
	ClassExternalAsset    Class = "external_asset"
)

type DenyReason ¶

type DenyReason string

DenyReason and FallbackReason provide stable accounting labels.

const (
	DenyInvalidKey      DenyReason = "invalid_key"
	DenyInvalidScope    DenyReason = "invalid_scope"
	DenyUnsupported     DenyReason = "unsupported"
	DenyOpenFailed      DenyReason = "open_failed"
	DenyOutOfBounds     DenyReason = "out_of_bounds"
	DenyReadFailed      DenyReason = "read_failed"
	DenyMmapFailed      DenyReason = "mmap_failed"
	DenyReleaseMismatch DenyReason = "release_mismatch"
)

type DirectViewOptions ¶

type DirectViewOptions struct {
	ElementSize         uintptr
	Alignment           uintptr
	TypeName            string
	RequireLittleEndian bool
}

DirectViewOptions controls validation before raw bytes are reinterpreted as a fixed-width typed slice.

type FallbackReason ¶

type FallbackReason string

const (
	FallbackMmapFailed FallbackReason = "mmap_failed"
	FallbackReadAt     FallbackReason = "readat"
)

type Handle ¶

type Handle struct {
	// contains filtered or unexported fields
}

Handle owns a live resource view. Bytes are valid until Release. Release is idempotent and updates accounting only once.

func (h *Handle) Bytes() []byte

func (h *Handle) Key() Key

func (h *Handle) Release() error

func (h *Handle) Released() bool

func (h *Handle) Scope() Scope

func (h *Handle) Source() Source

type Key ¶

type Key struct {
	Class      Class
	Namespace  string
	Kind       string
	Generation uint64
	PartID     uint64
	FileID     uint32
	Offset     int64
	Length     int64
	Checksum   uint64
	Version    uint16
	Encoding   string
	Section    Section
}

Key is the stable identity for a mapped or copied resource range.

Offset/Length are a physical range in FileID/object identity. Section is an optional logical refinement for internally sectioned assets. Checksum is a generic content checksum/digest slot; callers may use the lower bits when the source format stores uint32 checksums.

func (k Key) Equal(other Key) bool

func (k Key) Validate() error

type Manager ¶

type Manager struct {
	// contains filtered or unexported fields
}

Manager tracks resource handles and accounting. It intentionally does not choose a global cache policy; subsystems can wrap existing caches while using this manager for lifetime, pin, and stats visibility.

func NewManager() *Manager

func (m *Manager) AcquireBytes(key Key, scope Scope, source Source, data []byte, opts AcquireOptions) (*Handle, error)

func (m *Manager) AcquireFileRange(key Key, scope Scope, path string, opts AcquireOptions) (*Handle, error)

func (m *Manager) Float32View(h *Handle) ([]float32, error)

func (m *Manager) Float64View(h *Handle) ([]float64, error)

func (m *Manager) Int64View(h *Handle) ([]int64, error)

func (m *Manager) PinSummary() []Pin

func (m *Manager) RecordHit()

func (m *Manager) RecordMiss()

func (m *Manager) Stats() Stats

func (m *Manager) Uint16View(h *Handle) ([]uint16, error)

func (m *Manager) Uint32View(h *Handle) ([]uint32, error)

func (m *Manager) Uint64View(h *Handle) ([]uint64, error)

type Pin ¶

type Pin struct {
	ID     uint64
	Key    Key
	Scope  Scope
	Source Source
	Bytes  int64
	Reason string
	Root   string
	Path   string
}

Pin describes one active handle visible to maintenance planning. Root and Path carry storage identity for DB-local filtering; AcquireFileRange fills Path from the opened file path when callers leave ResourcePath empty.

func GlobalPinSummary() []Pin

type Scope ¶

type Scope struct {
	Kind       ScopeKind
	ID         string
	ParentID   string
	Collection string
	Namespace  string
	Generation uint64
	Reason     string
}

Scope ties a physical resource handle to a logical lifetime. Snapshot/read view scopes should anchor ordinary query/search handles; maintenance scopes anchor destructive planning and protection checks.

func NewScope(kind ScopeKind, id string) Scope

func (s Scope) Validate() error

func (s Scope) ValidateForKey(k Key) error

type ScopeKind ¶

type ScopeKind string

ScopeKind identifies the logical lifetime that owns a resource handle.

const (
	ScopeDB                 ScopeKind = "db"
	ScopeSnapshot           ScopeKind = "snapshot"
	ScopeCollectionReadView ScopeKind = "collection_read_view"
	ScopeManifestGeneration ScopeKind = "manifest_generation"
	ScopeMaintenance        ScopeKind = "maintenance"
	ScopePreparedQuery      ScopeKind = "prepared_query"
	ScopePreparedSearch     ScopeKind = "prepared_search"
	ScopeTypedRowReader     ScopeKind = "typed_row_reader"
	ScopeColumnPartReader   ScopeKind = "column_part_reader"
)

type Section ¶

type Section struct {
	Kind     string
	Category string
	Name     string
	Column   string
	Ordinal  uint32
}

Section identifies a logical sub-range within an immutable asset. Column-part assets use this to address descriptor, dictionary, vector, adjacency, and scalar payload sections without requiring one OS file per section.

func (s Section) Empty() bool

type Source ¶

type Source string

Source identifies how a handle's bytes are backed.

const (
	SourceMapped          Source = "mmap"
	SourceHeapCopy        Source = "heap_copy"
	SourceDerivedMetadata Source = "derived_metadata"
)

type Stats ¶

type Stats struct {
	ActiveHandles              int64
	ActiveMappedBytes          int64
	ActiveHeapCopyBytes        int64
	ActiveDerivedMetadataBytes int64

	TotalAcquires             uint64
	TotalReleases             uint64
	TotalMappedBytes          uint64
	TotalHeapCopyBytes        uint64
	TotalDerivedMetadataBytes uint64

	Hits          uint64
	Misses        uint64
	FallbackReads uint64
	Opens         uint64
	Closes        uint64
	Errors        uint64

	DirectViewSuccesses uint64
	DirectViewFailures  uint64

	DeniedByReason      map[DenyReason]uint64
	FallbacksByReason   map[FallbackReason]uint64
	ValidationModeReads map[ValidationMode]uint64
}

Stats is the common row+column resource accounting shape used by adapters and future column-part readers.

func GlobalStats() Stats

type ValidationMode ¶

type ValidationMode string

const (
	ValidationVerify       ValidationMode = "verify"
	ValidationCachedVerify ValidationMode = "cached_verify"
	ValidationSkipChecksum ValidationMode = "skip_checksums"
)