If specified, this function is called when a page is fetched from disk. * * @param rawPage The raw memory of the freshly-fetched page * @param pbn The absolute physical block number of the page * @param zone The block map zone to which the cache belongs * @param pageContext A pointer to client-specific data for the new page * * @return VDO_SUCCESS on success or VDO_BAD_PAGE if the page is incorrectly * formatted **/ typedef int VDOPageReadFunction(void *rawPage, PhysicalBlockNumber pbn, BlockMapZone *zone, void *pageContext); /** * Signature for a function to call when a page is written from the cache. * *
If specified, this function is called when a page is written to disk.
*
* @param rawPage The raw memory of the freshly-written page
* @param zone The block map zone to which the cache belongs
* @param pageContext A pointer to client-specific data for the new page
*
* @return whether the page needs to be rewritten
**/
typedef bool VDOPageWriteFunction(void *rawPage,
BlockMapZone *zone,
void *pageContext);
/**
* Construct a PageCache.
*
* @param [in] layer The physical layer to read and write
* @param [in] pageCount The number of cache pages to hold
* @param [in] readHook The function to be called when a page is read
* into the cache
* @param [in] writeHook The function to be called after a page is
* written from the cache
* @param [in] pageContextSize The size of the per-page context that will be
* passed to the read and write hooks
* @param [in] maximumAge The number of journal blocks before a dirtied
* page is considered old and must be written
* out
* @param [in] zone The block map zone which owns this cache
* @param [out] cachePtr A pointer to hold the cache
*
* @return a success or error code
**/
int makeVDOPageCache(PhysicalLayer *layer,
PageCount pageCount,
VDOPageReadFunction *readHook,
VDOPageWriteFunction *writeHook,
size_t pageContextSize,
BlockCount maximumAge,
BlockMapZone *zone,
VDOPageCache **cachePtr)
__attribute__((warn_unused_result));
/**
* Free the page cache structure and null out the reference to it.
*
* @param cachePtr a pointer to the cache to free
**/
void freeVDOPageCache(VDOPageCache **cachePtr);
/**
* Set the initial dirty period for a page cache.
*
* @param cache The cache
* @param period The initial dirty period to set
**/
void setVDOPageCacheInitialPeriod(VDOPageCache *cache, SequenceNumber period);
/**
* Switch the page cache into or out of read-only rebuild mode.
*
* @param cache The cache
* @param rebuilding true if the cache should be put into
* read-only rebuild mode, false otherwise
**/
void setVDOPageCacheRebuildMode(VDOPageCache *cache, bool rebuilding);
/**
* Check whether a page cache is active (i.e. has any active lookups,
* outstanding I/O, or pending I/O).
*
* @param cache The cache to check
*
* @return true if the cache is active
**/
bool isPageCacheActive(VDOPageCache *cache)
__attribute__((warn_unused_result));
/**
* Advance the dirty period for a page cache.
*
* @param cache The cache to advance
* @param period The new dirty period
**/
void advanceVDOPageCachePeriod(VDOPageCache *cache, SequenceNumber period);
/**
* Write one or more batches of dirty pages.
*
* All writable pages in the ancient era and some number in the old era
* are scheduled for writing.
*
* @param cache the VDO page cache
* @param batches how many batches to write now
* @param total how many batches (including those being written now) remain
* in this era
**/
void writeVDOPageCachePages(VDOPageCache *cache,
size_t batches,
size_t total);
/**
* Rotate the dirty page eras.
*
* Move all pages in the old era to the ancient era and then move
* the current era bin into the old era.
*
* @param cache the VDO page cache
**/
void rotateVDOPageCacheEras(VDOPageCache *cache);
// ASYNC
/**
* A completion awaiting a specific page. Also a live reference into the
* page once completed, until freed.
**/
typedef struct {
/** The generic completion */
VDOCompletion completion;
/** The cache involved */
VDOPageCache *cache;
/** The waiter for the pending list */
Waiter waiter;
/** The absolute physical block number of the page on disk */
PhysicalBlockNumber pbn;
/** Whether the page may be modified */
bool writable;
/** Whether the page is available */
bool ready;
/** The info structure for the page, only valid when ready */
PageInfo *info;
} VDOPageCompletion;
/**
* Initialize a VDO Page Completion, requesting a particular page from the
* cache.
*
* @param pageCompletion The VDOPageCompletion to initialize
* @param cache The VDO page cache
* @param pbn The absolute physical block of the desired page
* @param writable Whether the page can be modified
* @param parent The parent object
* @param callback The completion callback
* @param errorHandler The handler for page errors
*
* @note Once a completion has occurred for the getVDOPageAsync operation,
* the underlying page shall be busy (stuck in memory) until the
* VDOCompletion returned by this operation has been released.
**/
void initVDOPageCompletion(VDOPageCompletion *pageCompletion,
VDOPageCache *cache,
PhysicalBlockNumber pbn,
bool writable,
void *parent,
VDOAction *callback,
VDOAction *errorHandler);
/**
* Release a VDO Page Completion.
*
* The page referenced by this completion (if any) will no longer be
* held busy by this completion. If a page becomes discardable and
* there are completions awaiting free pages then a new round of
* page discarding is started.
*
* @param completion The completion to release
**/
void releaseVDOPageCompletion(VDOCompletion *completion);
/**
* Asynchronous operation to get a VDO page.
*
* May cause another page to be discarded (potentially writing a dirty page)
* and the one nominated by the completion to be loaded from disk.
*
* When the page becomes available the callback registered in the completion
* provided is triggered. Once triggered the page is marked busy until
* the completion is destroyed.
*
* @param completion the completion initialized my initVDOPageCompletion().
**/
void getVDOPageAsync(VDOCompletion *completion);
/**
* Mark a VDO page referenced by a completed VDOPageCompletion as dirty.
*
* @param completion a VDO Page Completion whose callback has been called
* @param oldDirtyPeriod the period in which the page was already dirty (0 if
* it wasn't)
* @param newDirtyPeriod the period in which the page is now dirty
**/
void markCompletedVDOPageDirty(VDOCompletion *completion,
SequenceNumber oldDirtyPeriod,
SequenceNumber newDirtyPeriod);
/**
* Request that a VDO page be written out as soon as it is not busy.
*
* @param completion the VDOPageCompletion containing the page
**/
void requestVDOPageWrite(VDOCompletion *completion);
/**
* Access the raw memory for a read-only page of a completed VDOPageCompletion.
*
* @param completion a vdo page completion whose callback has been called
*
* @return a pointer to the raw memory at the beginning of the page, or
* NULL if the page is not available.
**/
const void *dereferenceReadableVDOPage(VDOCompletion *completion);
/**
* Access the raw memory for a writable page of a completed VDOPageCompletion.
*
* @param completion a vdo page completion whose callback has been called
*
* @return a pointer to the raw memory at the beginning of the page, or
* NULL if the page is not available, or if the page is read-only
**/
void *dereferenceWritableVDOPage(VDOCompletion *completion);
/**
* Get the per-page client context for the page in a page completion whose
* callback has been invoked. Should only be called after dereferencing the
* page completion to validate the page.
*
* @param completion a vdo page completion whose callback has been invoked
*
* @return a pointer to the per-page client context, or NULL if
* the page is not available
**/
void *getVDOPageCompletionContext(VDOCompletion *completion);
/**
* Drain I/O for a page cache.
*
* @param cache The cache to drain
**/
void drainVDOPageCache(VDOPageCache *cache);
/**
* Invalidate all entries in the VDO page cache. There must not be any
* dirty pages in the cache.
*
* @param cache the cache to invalidate
*
* @return a success or error code
**/
int invalidateVDOPageCache(VDOPageCache *cache)
__attribute__((warn_unused_result));
// STATISTICS & TESTING
/**
* Get current cache statistics.
*
* @param cache the page cache
*
* @return the statistics
**/
AtomicPageCacheStatistics *getVDOPageCacheStatistics(VDOPageCache *cache)
__attribute__((warn_unused_result));
#endif // VDO_PAGE_CACHE_H