<!--
{
  "availability" : [
    "macOS: 27.0.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "FSKit",
  "identifier" : "/documentation/FSKit/FSVolume/DataCacheHandler",
  "metadataVersion" : "0.1.0",
  "role" : "Protocol",
  "symbol" : {
    "kind" : "Protocol",
    "modules" : [
      "FSKit"
    ],
    "preciseIdentifier" : "c:objc(pl)FSVolumeDataCacheHandler"
  },
  "title" : "FSVolume.DataCacheHandler"
}
-->

# FSVolume.DataCacheHandler

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

```
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`](/documentation/FSKit/FSVolume/DataCacheMode) and returns a
[`FSVolume.KernelCacheCoherencyType`](/documentation/FSKit/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`](/documentation/FSKit/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`](/documentation/FSKit/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`](/documentation/FSKit/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`](/documentation/FSKit/FSVolume/KernelCacheCoherencyType/readCache),
[`FSVolume.KernelCacheCoherencyType.writeThrough`](/documentation/FSKit/FSVolume/KernelCacheCoherencyType/writeThrough), and [`FSVolume.KernelCacheCoherencyType.writeBack`](/documentation/FSKit/FSVolume/KernelCacheCoherencyType/writeBack) modes
support deferred closing.

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

|Cache mode                                                                   |Coherency type                                                                                                                                                                                                                                                                                                                       |
|-----------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|``doc://FSKit/documentation/FSKit/FSVolume/DataCacheMode/none``              |``doc://FSKit/documentation/FSKit/FSVolume/KernelCacheCoherencyType/noCache``                                                                                                                                                                                                                                                        |
|``doc://FSKit/documentation/FSKit/FSVolume/DataCacheMode/readWithCache``     |``doc://FSKit/documentation/FSKit/FSVolume/KernelCacheCoherencyType/noCache`` or ``doc://FSKit/documentation/FSKit/FSVolume/KernelCacheCoherencyType/readCache``                                                                                                                                                                     |
|``doc://FSKit/documentation/FSKit/FSVolume/DataCacheMode/readWriteWithCache``|``doc://FSKit/documentation/FSKit/FSVolume/KernelCacheCoherencyType/noCache``, ``doc://FSKit/documentation/FSKit/FSVolume/KernelCacheCoherencyType/readCache``, ``doc://FSKit/documentation/FSKit/FSVolume/KernelCacheCoherencyType/writeBack`` or ``doc://FSKit/documentation/FSKit/FSVolume/KernelCacheCoherencyType/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  |
|----------------------------------------------------------------------------------|----------------|
|``doc://FSKit/documentation/FSKit/FSVolume/KernelCacheCoherencyType/noCache``     |Least permissive|
|``doc://FSKit/documentation/FSKit/FSVolume/KernelCacheCoherencyType/readCache``   |                |
|``doc://FSKit/documentation/FSKit/FSVolume/KernelCacheCoherencyType/writeBack``   |                |
|``doc://FSKit/documentation/FSKit/FSVolume/KernelCacheCoherencyType/writeThrough``|Most permissive |

When transitioning to more permissive caching, kernel performs an “upgrade” by calling [`upgrade(_:cacheMode:context:replyHandler:)`](/documentation/FSKit/FSVolume/DataCacheHandler/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:)`](/documentation/FSKit/FSVolume/setCacheState(for:cacheMode:coherencyType:action:)) when conditions change.
In this scenario, set the `action` to [`FSVolume.KernelCacheCoherencyAction.push`](/documentation/FSKit/FSVolume/KernelCacheCoherencyAction/push), [`FSVolume.KernelCacheCoherencyAction.pushInvalidate`](/documentation/FSKit/FSVolume/KernelCacheCoherencyAction/pushInvalidate), or [`FSVolume.KernelCacheCoherencyAction.invalidate`](/documentation/FSKit/FSVolume/KernelCacheCoherencyAction/invalidate).
Handle any dirty data by flushing or purging it before downgrading with this method call.

> Important: If a file system doesn’t conform to this protocol, the kernel may still cache it.
> However, such a file system has no control over caching behavior; the kernel caches data as it sees fit.

## Topics

### Opening and closing items

[`open(_:modes:cacheMode:context:replyHandler:)`](/documentation/FSKit/FSVolume/DataCacheHandler/open(_:modes:cacheMode:context:replyHandler:))

Opens an item with cache mode negotiation.

[`FSOpenItemResult`](/documentation/FSKit/FSOpenItemResult)

The result of an open-item call.

[`close(_:context:replyHandler:)`](/documentation/FSKit/FSVolume/DataCacheHandler/close(_:context:replyHandler:))

Closes an item and releases associated cache resources.

[`FSVolume.DataCacheMode`](/documentation/FSKit/FSVolume/DataCacheMode)

A type that defines the cache mode requested by the kernel for data operations.

[`FSContext`](/documentation/FSKit/FSContext)

A context object that provides information about the initiator of a file system operation.

### Changing cache behavior

[`upgrade(_:cacheMode:context:replyHandler:)`](/documentation/FSKit/FSVolume/DataCacheHandler/upgrade(_:cacheMode:context:replyHandler:))

Upgrades the item cache mode to a less restrictive level, allowing more caching.

[`FSItem`](/documentation/FSKit/FSItem)

A distinct object in a file hierarchy, such as a file, directory, symlink, socket, and more.

[`FSContext`](/documentation/FSKit/FSContext)

A context object that provides information about the initiator of a file system operation.

[`FSUpgradeItemResult`](/documentation/FSKit/FSUpgradeItemResult)

The result of an upgrade-item call.

### Inspecting cache behavior

[`isDataCacheInhibited`](/documentation/FSKit/FSVolume/DataCacheHandler/isDataCacheInhibited)

A Boolean value that instructs FSKit not to call this protocol’s methods, even if the volume conforms to it.


---

Copyright &copy; 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)