README.md
1VDKQueue
2=======
3
4A modern, faster, better version of UKKQueue.
5
6<http://incident57.com/codekit>
7
8
9about
10-----
11
12VDKQueue is an Objective-C wrapper around kernel queues (kQueues).
13It allows you to watch a file or folder for changes and be notified when they occur.
14
15VDKQueue is a modern, streamlined and much faster version of UKKQueue, which was originally written in 2003 by Uli Kusterer.
16Objective-C has come a long way in the past nine years and UKKQueue was long in the tooth. VDKQueue is better in several ways:
17
18 -- The number of method calls is vastly reduced.
19 -- Grand Central Dispatch is used in place of Uli's "threadProxy" notifications (much faster)
20 -- Memory footprint is roughly halved, since VDKQueue creates less overhead
21 -- Fewer locks are taken, especially in loops (faster)
22 -- The code is *much* cleaner and simpler!
23 -- There is only one .h and one .m file to include.
24
25VDKQueue also fixes long-standing bugs in UKKQueue. For example: OS X limits the number of open file descriptors each process
26may 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.
27
28
29
30performance
31-----------
32
33Adding 1,945 file paths to a UKKQueue instance took, on average, 80ms.
34Adding those same files to a VDKQueue instance took, on average, 65ms.
35
36VDKQueue processes and pushes out notifications about file changes roughly 50-70% faster than UKKQueue.
37
38All tests conducted on a 2008 MacBook Pro 2.5Ghz with 4GB of RAM running OS 10.7.3 using Xcode and Instruments (time profiler).
39
40
41
42
43requirements
44------------
45
46VDKQueue requires Mac OS X 10.6+ because it uses Grand Central Dispatch.
47
48VDKQueue does not support garbage collection. If you use garbage collection, you are lazy. Shape up.
49
50VDKQueue does not currently use ARC, although it should be straightforward to convert if you wish. (Don't be the guy that can't manually manage memory, though.)
51
52
53
54
55license
56-------
57
58Created by Bryan D K Jones on 28 March 2012
59Copyright 2013 Bryan D K Jones
60
61Based heavily on UKKQueue, which was created and copyrighted by Uli Kusterer on 21 Dec 2003.
62
63This 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:
64
651. 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.
66
672. Altered source versions must be plainly marked as such, and must not be misrepresented as being the original software.
68
693. This notice may not be removed or altered from any source distribution.
70