Contents

FSVolume.DataCacheHandler

Methods and properties implemented by volumes that coordinate kernel-level data caching.

Declaration

protocol DataCacheHandler : NSObjectProtocol

Overview

A volume that conforms to this protocol enables kernel data caching for improved I/O performance. This protocol allows filesystem modules to negotiate cache modes with the kernel and manage cache coherency.

When a file opens, the module receives the requested FSVolume.DataCacheMode and returns a FSVolume.KernelCacheCoherencyType indicating the kind of caching behavior it can support. The kernel then caches data according to the granted coherency type. The module can dynamically upgrade or downgrade cache modes as conditions change.

The kernel requests a caching mode expressed as a FSVolume.DataCacheMode value, which indicates what the kernel would like to cache (read-only data, read-write data, or no caching). The module then replies with a specific FSVolume.KernelCacheCoherencyType value, which defines how the kernel should cache the data (no caching, read-only caching, write-through caching, or write-back caching). When the module detects an asynchronous condition requiring a change in caching mode (such as an lease break), the module uses a value from FSVolume.KernelCacheCoherencyAction to instruct the kernel how to handle any cached data (push dirty pages, invalidate cache, or update coherency mode).

The protocol supports deferred closing, where the kernel maintains cache state even after a file is closed, enabling improved performance for frequently accessed files. The FSVolume.KernelCacheCoherencyType.readCache, FSVolume.KernelCacheCoherencyType.writeThrough, and FSVolume.KernelCacheCoherencyType.writeBack modes support deferred closing.

The following table shows the mapping of cache modes to supported coherency types.

Cache mode

Coherency type

None

Nocache

Readwithcache

Nocache or Readcache

Readwritewithcache

Nocache, Readcache, Writeback or Writethrough

Supporting coherency transitions

Transitioning between coherency types requires different behaviors from your volume implementation, depending on whether the new type is more or less permissive than its current value. The following table expresses the permissiveness of the coherency types.

Coherency type

Permissiveness

Nocache

Least permissive

Readcache

Writeback

Writethrough

Most permissive

When transitioning to more permissive caching, kernel performs an “upgrade” by calling upgrade(_:cacheMode:context:replyHandler:). Your volume doesn’t need to perform a flush or purge when upgrading to a more permissive coherency type.

Transitioning to a less permissive coherency type is considered a “downgrade”. Your module initiates this process by calling setCacheState(for:cacheMode:coherencyType:action:) when conditions change. In this scenario, set the action to FSVolume.KernelCacheCoherencyAction.push, FSVolume.KernelCacheCoherencyAction.pushInvalidate, or FSVolume.KernelCacheCoherencyAction.invalidate. Handle any dirty data by flushing or purging it before downgrading with this method call.

Topics

Opening and closing items

Changing cache behavior

Inspecting cache behavior

See Also

Implementing optional handlers