File-src-minisql-storage-buffer-pool-ml-1867626530.md

src/minisql/storage/buffer_pool.ml

Home · Files

Provides minisql storage buffer pool facilities for this project.

Package: minisql.storage.buffer_pool

Reachable from entry: yes

Imports

• minisql/common/limits.ml as limits → src/minisql/common/limits.ml
• minisql/storage/page.ml as page → src/minisql/storage/page.ml
• minisql/storage/paged_file.ml as paged_file → src/minisql/storage/paged_file.ml
• std/ds/hashmap.ml as hashmap → ../MiniLangCompilerML/std/ds/hashmap.ml — external dependency
• std/threading.ml as threading → ../MiniLangCompilerML/std/threading.ml — external dependency

Declarations

BUFFER_POOL_EXHAUSTED

const BUFFER_POOL_EXHAUSTED = 9009

Defines the buffer pool exhausted constant used by the minisql storage buffer pool module.

View source

• minisql.storage.buffer_pool.BufferFrame — struct
• minisql.storage.buffer_pool.BufferPool — struct
• minisql.storage.buffer_pool.BufferPoolStats — struct

cachedRowCount

function cachedRowCount(cache, tablePath)

Returns a previously verified autocommit row count or void on a cache miss.

Parameter	Type	Default	Description
cache	dynamic	—	cache value consumed by this operation.
tablePath	dynamic	—	Path associated with table.

View source

chooseReadVictim

function chooseReadVictim(cache)

Chooses an empty frame or an unreferenced CLOCK victim while the cache guard is held. Read frames are never pinned or dirty, so two passes always suffice.

Parameter	Type	Default	Description
cache	dynamic	—	cache value consumed by this operation.

View source

chooseVictim

function chooseVictim(pool)

Performs the choose victim operation for this module. Inputs: pool. Returns the produced value or propagates a structured error from validation or delegated operations.

Parameter	Type	Default	Description
pool	dynamic	—	pool value consumed by this operation.

View source

clearReadCache

function clearReadCache(cache)

Invalidates all cached base pages after a successful database mutation.

Parameter	Type	Default	Description
cache	dynamic	—	cache value consumed by this operation.

View source

close

function close(pool)

Closes close owned by the minisql storage buffer pool module. Inputs: pool. Returns the operation result and propagates validation, storage, or platform errors unchanged.

Parameter	Type	Default	Description
pool	dynamic	—	pool value consumed by this operation.

View source

CLOSED_HANDLE

const CLOSED_HANDLE = 9008

Defines the closed handle constant used by the minisql storage buffer pool module.

View source

closeReadCache

function closeReadCache(cache)

Closes a read cache after the owning database execution gate is empty.

Parameter	Type	Default	Description
cache	dynamic	—	cache value consumed by this operation.

View source

componentName

function componentName()

Performs the componentName operation for the minisql storage buffer pool module. Takes no caller-supplied inputs. Returns the produced value or propagates a structured error from validation or delegated operations.

View source

create

function create(capacity)

Creates create for the minisql storage buffer pool module. Inputs: capacity. Returns the produced value or propagates a structured error from validation or delegated operations.

Parameter	Type	Default	Description
capacity	dynamic	—	capacity value consumed by this operation.

View source

createForBytes

function createForBytes(maxBytes, pageSize)

Creates the for bytes. Inputs: maxBytes, pageSize. Returns the produced value or propagates a structured error from validation or delegated operations.

Parameter	Type	Default	Description
maxBytes	dynamic	—	maxBytes value consumed by this operation.
pageSize	dynamic	—	pageSize value consumed by this operation.

View source

createReadCache

function createReadCache(maxBytes, pageSize)

Creates the concurrent read cache for a configured memory budget.

Parameter	Type	Default	Description
maxBytes	dynamic	—	maxBytes value consumed by this operation.
pageSize	dynamic	—	pageSize value consumed by this operation.

View source

data

function data(guard)

Performs the data operation for this module. Inputs: guard. Returns the produced value or propagates a structured error from validation or delegated operations.

Parameter	Type	Default	Description
guard	dynamic	—	guard value consumed by this operation.

View source

emptyFrame

function emptyFrame()

Performs the empty frame operation for this module. Takes no caller-supplied inputs. Returns the produced value or propagates a structured error from validation or delegated operations.

View source

fail

function fail(code, operation, message)

Performs the fail operation for the minisql storage buffer pool module. Inputs: code, operation, message. Returns the produced value or propagates a structured error from validation or delegated operations.

Parameter	Type	Default	Description
code	dynamic	—	code value consumed by this operation.
operation	dynamic	—	operation value consumed by this operation.
message	dynamic	—	Human-readable message associated with the operation.

View source

findFrame

function findFrame(pool, pagedFile, pageNumber)

Finds the frame. Inputs: pool, pagedFile, pageNumber. Returns the produced value or propagates a structured error from validation or delegated operations.

Parameter	Type	Default	Description
pool	dynamic	—	pool value consumed by this operation.
pagedFile	dynamic	—	pagedFile value consumed by this operation.
pageNumber	dynamic	—	pageNumber value consumed by this operation.

View source

flushAll

function flushAll(pool)

Flushes the all. Inputs: pool. Returns the operation result and propagates validation, storage, or platform errors unchanged.

Parameter	Type	Default	Description
pool	dynamic	—	pool value consumed by this operation.

View source

flushFrame

function flushFrame(pool, frameIndex)

Flushes the frame. Inputs: pool, frameIndex. Returns the operation result and propagates validation, storage, or platform errors unchanged.

Parameter	Type	Default	Description
pool	dynamic	—	pool value consumed by this operation.
frameIndex	dynamic	—	Zero-based index of frame.

View source

frameMatchesFile

function frameMatchesFile(frame, pagedFile)

Performs the frame matches file operation for this module. Inputs: frame, pagedFile. Returns the produced value or propagates a structured error from validation or delegated operations.

Parameter	Type	Default	Description
frame	dynamic	—	frame value consumed by this operation.
pagedFile	dynamic	—	pagedFile value consumed by this operation.

View source

INVALID_ARGUMENT

const INVALID_ARGUMENT = 9001

Fixed-capacity buffer pool with explicit pin/unpin guards and CLOCK eviction.

View source

invalidateFile

function invalidateFile(pool, pagedFile)

Performs the invalidate file operation for this module. Inputs: pool, pagedFile. Returns the produced value or propagates a structured error from validation or delegated operations.

Parameter	Type	Default	Description
pool	dynamic	—	pool value consumed by this operation.
pagedFile	dynamic	—	pagedFile value consumed by this operation.

View source

isImplemented

function isImplemented()

Returns whether implemented satisfies the condition required by the minisql storage buffer pool module. Takes no caller-supplied inputs. Returns a boolean result; invalid input or delegated failures are reported as structured errors.

View source

markDirty

function markDirty(guard)

Marks the dirty. Inputs: guard. Returns the produced value or propagates a structured error from validation or delegated operations.

Parameter	Type	Default	Description
guard	dynamic	—	guard value consumed by this operation.

View source

pageCapacity

function pageCapacity(maxBytes, pageSize)

Converts a byte budget to pages using the database's validated page size.

Parameter	Type	Default	Description
maxBytes	dynamic	—	maxBytes value consumed by this operation.
pageSize	dynamic	—	pageSize value consumed by this operation.

View source

• minisql.storage.buffer_pool.PageGuard — struct

pin

function pin(pool, pagedFile, pageNumber)

Performs the pin operation for this module. Inputs: pool, pagedFile, pageNumber. Returns the produced value or propagates a structured error from validation or delegated operations.

Parameter	Type	Default	Description
pool	dynamic	—	pool value consumed by this operation.
pagedFile	dynamic	—	pagedFile value consumed by this operation.
pageNumber	dynamic	—	pageNumber value consumed by this operation.

View source

PINNED_PAGE

const PINNED_PAGE = 9010

Defines the pinned page constant used by the minisql storage buffer pool module.

View source

readCached

function readCached(cache, pagedFile, pageNumber)

Reads through the concurrent cache. Disk I/O occurs without holding the cache guard; a second lookup collapses races when two readers miss together.

Parameter	Type	Default	Description
cache	dynamic	—	cache value consumed by this operation.
pagedFile	dynamic	—	pagedFile value consumed by this operation.
pageNumber	dynamic	—	pageNumber value consumed by this operation.

View source

• minisql.storage.buffer_pool.ReadCacheFrame — struct

readCacheKey

function readCacheKey(pagedFile, pageNumber)

Builds an unambiguous cache key; page paths cannot contain a NUL character.

Parameter	Type	Default	Description
pagedFile	dynamic	—	pagedFile value consumed by this operation.
pageNumber	dynamic	—	pageNumber value consumed by this operation.

View source

readCacheStats

function readCacheStats(cache)

Returns a synchronized diagnostic snapshot.

Parameter	Type	Default	Description
cache	dynamic	—	cache value consumed by this operation.

View source

• minisql.storage.buffer_pool.ReadPageCache — struct
• minisql.storage.buffer_pool.ReadPageCacheStats — struct

release

function release(guard)

Performs the release operation for the minisql storage buffer pool module. Inputs: guard. Returns the operation result and propagates validation, storage, or platform errors unchanged.

Parameter	Type	Default	Description
guard	dynamic	—	guard value consumed by this operation.

View source

rememberRowCount

function rememberRowCount(cache, tablePath, rowCount)

Publishes a verified autocommit row count. Concurrent readers may race to publish the same value because writers are excluded by the execution gate.

Parameter	Type	Default	Description
cache	dynamic	—	cache value consumed by this operation.
tablePath	dynamic	—	Path associated with table.
rowCount	dynamic	—	Number of row to process.

View source

stats

function stats(pool)

Performs the stats operation for this module. Inputs: pool. Returns the produced value or propagates a structured error from validation or delegated operations.

Parameter	Type	Default	Description
pool	dynamic	—	pool value consumed by this operation.

View source

targetMilestone

function targetMilestone()

Performs the targetMilestone operation for the minisql storage buffer pool module. Takes no caller-supplied inputs. Returns the produced value or propagates a structured error from validation or delegated operations.

View source

validateGuard

function validateGuard(guard, operation)

Validates the guard. Inputs: guard, operation. Returns success after all invariants hold; violations are reported as structured errors.

Parameter	Type	Default	Description
guard	dynamic	—	guard value consumed by this operation.
operation	dynamic	—	operation value consumed by this operation.

View source

validatePool

function validatePool(pool, operation)

Validates the pool. Inputs: pool, operation. Returns success after all invariants hold; violations are reported as structured errors.

Parameter	Type	Default	Description
pool	dynamic	—	pool value consumed by this operation.
operation	dynamic	—	operation value consumed by this operation.

View source

validateReadCache

function validateReadCache(cache, operation)

Validates a read cache before synchronization or I/O.

Parameter	Type	Default	Description
cache	dynamic	—	cache value consumed by this operation.
operation	dynamic	—	operation value consumed by this operation.

View source