VDKQueue

A modern, faster, better version of UKKQueue.

https://github.com/coeur/VDKQueue

about

VDKQueue is an Objective-C wrapper around kernel queues (kQueues). It allows you to watch a file or folder for changes and be notified when they occur.

VDKQueue is a modern, streamlined and much faster version of UKKQueue, which was originally written in 2003 by Uli Kusterer. Objective-C has come a long way in the past nine years and UKKQueue was long in the tooth. VDKQueue is better in several ways:

-- The number of method calls is vastly reduced.
-- Grand Central Dispatch is used in place of Uli's "threadProxy" notifications (much faster)
-- Memory footprint is roughly halved, since VDKQueue creates less overhead
-- Fewer locks are taken, especially in loops (faster)
-- The code is *much* cleaner and simpler!
-- There is only one .h and one .m file to include.

VDKQueue also fixes long-standing bugs in UKKQueue. For example: OS X limits the number of open file descriptors each process may have to about 3,000. If UKKQueue fails to open a new file descriptor because it has hit this limit, it will crash. VDKQueue will not.

requirements

VDKQueue uses ARC.

alternatives API

Alternative solutions to VDKQueue, from archaic to modern. But they all rely on kQueues under the hood.

• ✅︎ FreeBSD 4.1+: Kernel Queue API (kevent and kqueue) (https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/kqueue.2.html)

  Example: ✘ SKQueue (https://github.com/daniel-pedersen/SKQueue) but claimed to crash and be superseded by SFSMonitor (https://stackoverflow.com/a/62167224)

• ❌ macOS 10.1–10.8: FNSubscribe and FNNotify API (https://developer.apple.com/documentation/coreservices/1566843-fnsubscribebypath) "the FNNotify API has been supplanted by the FSEvents API" (https://github.com/phracker/MacOSX-SDKs/blob/master/MacOSX10.7.sdk/System/Library/Frameworks/AppKit.framework/Versions/C/Headers/NSWorkspace.h)

• ✅︎ macOS 10.5+: File System Events API (FSEventStreamCreate) (https://developer.apple.com/documentation/coreservices/file_system_events) "File system events are intended to provide notification of changes with directory-level granularity. For most purposes, this is sufficient. In some cases, however, you may need to receive notifications with finer granularity. For example, you might need to monitor only changes made to a single file. For that purpose, the kernel queue (kqueue) notification system is more appropriate. If you are monitoring a large hierarchy of content, you should use file system events instead, however, because kernel queues are somewhat more complex than kernel events, and can be more resource intensive because of the additional user-kernel communication involved." (https://developer.apple.com/library/archive/documentation/Darwin/Conceptual/FSEvents_ProgGuide/KernelQueues/KernelQueues.html)

  Example: ✔ UKFSEventsWatcher (https://github.com/uliwitness/UKFileWatcher) Example: ✔ EonilFSEvents (https://github.com/eonil/FSEvents) Example: ✔ FileWatcher (https://github.com/eonist/FileWatcher)

• ✅︎ macOS 10.6+: Grand Central Dispatch API to monitor virtual filesystem nodes (DISPATCH_SOURCE_TYPE_VNODE) (https://developer.apple.com/documentation/dispatch/dispatch_source_type_vnode) "GCD uses kqueue under the hood and the same capabilities are made available." (https://www.reddit.com/r/programming/comments/l6j3g/using_kqueue_in_cocoa/c2q74yy)

  Example: ✘ RSTDirectoryMonitor (https://github.com/varuzhnikov/HelloWorld) but unmaintained as a standalone project (abandoned 2013) Example: ✘ DirectoryMonitor (https://github.com/robovm/apple-ios-samples/blob/master/ListerforwatchOSiOSandOSX/Swift/ListerKit/DirectoryMonitor.swift) but unmaintained (abandoned 2016) Example: ✘ TABFileMonitor (https://github.com/tblank555/iMonitorMyFiles/tree/master/iMonitorMyFiles/Classes) but unmaintained (abandoned 2016) Example: ✔ DTFolderMonitor (https://github.com/Cocoanetics/DTFoundation/tree/develop/Core/Source)

• ❌ macOS 10.7+: NSFilePresenter API (https://developer.apple.com/documentation/foundation/nsfilepresenter?language=objc) "They're buggy, broken, and Apple is haven't willing to fix them for last 4 years." (https://stackoverflow.com/a/26878163)

• ✅︎ macOS 10.10+: DispatchSource API (makeFileSystemObjectSource) (https://developer.apple.com/documentation/dispatch/dispatchsource/2300040-makefilesystemobjectsource) "DispatchSource is just the Swift version of gcd dispatch sources" (bdkjones#22 (comment))

  Example: ✔ SFSMonitor (https://github.com/ClassicalDude/SFSMonitor)

license

Created by Bryan D K Jones on 28 March 2012 Copyright 2013 Bryan D K Jones

Based heavily on UKKQueue, which was created and copyrighted by Uli Kusterer on 21 Dec 2003.

This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages arising from the use of this software. Permission is granted to anyone to use this software for any purpose, including commercial applications, and to alter it and redistribute it freely, subject to the following restrictions:

1. The origin of this software must not be misrepresented; you must not claim that you wrote the original software. If you use this software in a product, an acknowledgment in the product documentation would be appreciated but is not required.

2. Altered source versions must be plainly marked as such, and must not be misrepresented as being the original software.

3. This notice may not be removed or altered from any source distribution.