Updating an FSKit module to use the new Handler protocols

I have a file system extension that currently uses the various now-deprecated Operations protocols. I have a few questions about moving to the new Handler protocols.


First, my module is going to maintain backwards compatibility with macOS Sequoia for the foreseeable future, but I would also like to be able to take advantage of new FSKit features for users who are on newer OS versions. What approach would you recommend:

  • Having an FSVolume conform to both the various Operations and Handler protocols (e.g. both FSVolumeKernelOffloadedIOOperations and FSVolume.KernelOffloadedIOHandler with the latter tagged with @available)
    • an immediate issue I see trying to do this is I run into the error Method 'activate(options:)' with Objective-C selector 'activateWithOptions:replyHandler:' conflicts with previous declaration with the same Objective-C selector when trying to conform to both FSVolume.Handler and FSVolume.Operations.
  • Having two separate FSVolume implementations, one used for older OS versions with Operations support and one used on newer OS versions with Handler support?
  • Keeping the use of pre-existing Operations protocols while only using the Handlers for newer features (e.g. things like SeekRegionHandler)

Second, I see at https://developer.apple.com/documentation/fskit/fsvolumehandlerresult/requestedattributes that I must populate all requested attributes. Does this value only have a meaning if the initializer for the actual concrete result type has an initializer that takes in a FSItem.Attributes instance, or is there some way I’m supposed to populate those? (As a concrete example, FSCheckAccessResult has init(accessAllowed:) which doesn’t take in any attributes.)

Answered by Frameworks Engineer in 891100022

Regarding your second question, you are correct. FSCheckAccessResult.requestedAttributes can be ignored. (The same applies for all concrete result objects where the initializer doesn't take an instance of FSItem.Attributes).

an immediate issue I see trying to do this is I run into the error Method 'activate(options:)' with Objective-C selector 'activateWithOptions:replyHandler:' conflicts with previous declaration with the same Objective-C selector when trying to conform to both FSVolume.Handler and FSVolume.Operations.

Please file a FeedBack regarding this issue and post its number here.

Our expectation had been to have a volume conform to both.

Regarding your second question, you are correct. FSCheckAccessResult.requestedAttributes can be ignored. (The same applies for all concrete result objects where the initializer doesn't take an instance of FSItem.Attributes).

@Systems Engineer looks like Feedback Assistant is back up, so I made FB23036931 regarding this

Thanks to both of you for the answers!

Seems like the issue regarding Handler + Operations support is fixed, so I ended up verifying the fix to FB23036931.

Unfortunately, a few days after closing it, I later realized that the same issue seems to apply to ReadWriteOperations + ReadWriteHandler as well as the two kernel offloaded IO protocols, so I also made FB24356249.

Seems like FB24356249 unfortunately wasn't fixed in time (at least as tested with the Xcode 27 RC).

If a volume conforms to all of the legacy Operations protocols and only some of the newer Handler protocols, will macOS 27 clients handle this properly, using the newer implementations where available and the old ones where not? Experimentally, on a macOS 27 RC VM, it seems to work, although I'm not sure if this has risk of breakage.

Accepted Answer

Unfortunately, it doesn't look like there is a plan to fix this as FB24356249 was closed as "works as currently designed." (I'm guessing that since they're already released it would be too much to change the protocol.)

However, I did receive a response to FB24356249 that outlines a solution to this, which I'll post here for the benefit of anyone who finds this thread later:

Thank you for reporting this issue. Unfortunately there is no one FSVolume subclass which will satisfy both FSVolume.ReadWriteOperations and FSVolume.ReadWriteHandler. What we have found works is to create an FSVolume class containing internalRead(from:at:length:into:replyHandler:) functions. Then create two subclasses. Each subclass conforms to either FSVolume.ReadWriteOperations or FSVolume.ReadWriteHandler and the included functions just wrap the internalRead(from:at:length:into:replyHandler:) calls. In this way, the two subclasses only contain wrappers and all core logic is contained in the common FSVolume subclass.

By internalRead(from:at:length:into:replyHandler:), we mean functions implementing the underlying read and write operations and having names different from those in FSVolume.ReadWriteHandler.

A decent amount of added boilerplate, but other than that it works well enough.