<!--
{
  "availability" : [
    "macOS: 27.0.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "FSKit",
  "identifier" : "/documentation/FSKit/FSVolume/setCacheState(for:cacheMode:coherencyType:action:)",
  "metadataVersion" : "0.1.0",
  "role" : "Instance Method",
  "symbol" : {
    "kind" : "Instance Method",
    "modules" : [
      "FSKit"
    ],
    "preciseIdentifier" : "c:objc(cs)FSVolume(im)setCacheStateForItem:cacheMode:coherencyType:coherencyAction:"
  },
  "title" : "setCacheState(for:cacheMode:coherencyType:action:)"
}
-->

# setCacheState(for:cacheMode:coherencyType:action:)

Sends a synchronous cache state update request from the module to the kernel.

```
func setCacheState(for item: FSItem, cacheMode: FSVolume.DataCacheMode, coherencyType: FSVolume.KernelCacheCoherencyType, action: FSVolume.KernelCacheCoherencyAction) -> (any Error)?
```

## Parameters

`item`

The item for which to update the cache state.

`cacheMode`

The new cache mode to apply.

`coherencyType`

The new coherency type to apply.

`action`

The action for the kernel to perform on cached data (push, invalidate, update, or revoke).

## Return Value

An error if the kernel was unable to complete the requested cache state change, or `nil` on success.

## Discussion

Volumes conforming to [`FSVolume.DataCacheHandler`](/documentation/FSKit/FSVolume/DataCacheHandler) call this method to proactively notify
the kernel about cache policy changes that need to be applied immediately.
This allows module-initiated updates outside the normal open/close/upgrade/downgrade flow.

When downgrading coherency type, the action must be [`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)
to instruct the kernel how to handle cached data.
If the action fails, the cache state remains unchanged and the method returns an error.

> Important: This method must be called without holding any module-internal locks.
> The kernel may issue additional operations back into the module to satisfy cache state changes,
> which could result in deadlock if locks are held.

> Note: This method is only functional for volumes that conform to ``doc://FSKit/documentation/FSKit/FSVolume/DataCacheHandler``.
> For volumes that don’t conform to the protocol, this method returns `ENOTSUP`.

---

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)