Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 67 lines (47 sloc) 2.17 kb
9aa7978 @nex3 Add a README.
authored
1 # rb-inotify
2
3 This is a simple wrapper over the [inotify](http://en.wikipedia.org/wiki/Inotify) Linux kernel subsystem
4 for monitoring changes to files and directories.
5 It uses the [FFI](http://wiki.github.com/ffi/ffi) gem to avoid having to compile a C extension.
6
0568729 @nex3 Link to API docs on rdoc.info.
authored
7 [API documentation is available on rdoc.info](http://rdoc.info/projects/nex3/rb-inotify).
8
9aa7978 @nex3 Add a README.
authored
9 ## Basic Usage
10
11 The API is similar to the inotify C API, but with a more Rubyish feel.
12 First, create a notifier:
13
14 notifier = INotify::Notifier.new
15
16 Then, tell it to watch the paths you're interested in
17 for the events you care about:
18
19 notifier.watch("path/to/foo.txt", :modify) {puts "foo.txt was modified!"}
20 notifier.watch("path/to/bar", :moved_to, :create) do |event|
21 puts "#{event.name} is now in path/to/bar!"
22 end
23
24 Inotify can watch directories or individual files.
25 It can pay attention to all sorts of events;
26 for a full list, see [the inotify man page](http://www.tin.org/bin/man.cgi?section=7&topic=inotify).
27
28 Finally, you get at the events themselves:
29
30 notifier.run
31
32 This will loop infinitely, calling the appropriate callbacks when the files are changed.
33 If you don't want infinite looping,
34 you can also block until there are available events,
35 process them all at once,
36 and then continue on your merry way:
37
38 notifier.process
39
40 ## Advanced Usage
41
42 Sometimes it's necessary to have finer control over the underlying IO operations
43 than is provided by the simple callback API.
14863b8 @nex3 Update the README for the new to_io thing.
authored
44 The trick to this is that the \{INotify::Notifier#to_io Notifier#to_io} method
45 returns a fully-functional IO object,
9aa7978 @nex3 Add a README.
authored
46 with a file descriptor and everything.
47 This means, for example, that it can be passed to `IO#select`:
48
49 # Wait 10 seconds for an event then give up
14863b8 @nex3 Update the README for the new to_io thing.
authored
50 if IO.select([notifier.to_io], [], [], 10)
9aa7978 @nex3 Add a README.
authored
51 notifier.process
52 end
53
54 It can even be used with EventMachine:
55
56 require 'eventmachine'
57
58 EM.run do
14863b8 @nex3 Update the README for the new to_io thing.
authored
59 EM.watch notifier.to_io do
9aa7978 @nex3 Add a README.
authored
60 notifier.process
61 end
62 end
14863b8 @nex3 Update the README for the new to_io thing.
authored
63
64 Unfortunately, this currently doesn't work under JRuby.
65 JRuby currently doesn't use native file descriptors for the IO object,
66 so we can't use the notifier's file descriptor as a stand-in.
Something went wrong with that request. Please try again.