Skip to content
An FFI wrapper for kqueue
Find file
Latest commit 7653794 @mat813 v0.2.4.
Failed to load latest commit information.
lib v0.2.4.
.gitignore Move from jeweler to bundler.
Gemfile Move from jeweler to bundler.
MIT-LICENSE Add real project stuff, like a README and a Rakefile. Remove WARNING and add Contributing.
Rakefile Move from jeweler to bundler.
VERSION Version bump to 0.1.0
rb-kqueue.gemspec v0.2.4.


This is a simple wrapper over the kqueue BSD event notification interface (supported on FreeBSD, NetBSD, OpenBSD, and Darwin). It uses the FFI gem to avoid having to compile a C extension.

API documentation is available on


The API is similar to the kqueue C API, but with a more Rubyish feel. First, create a queue:

queue =

Then, tell it to watch the events you're interested in:

queue.watch_file("path/to/foo.txt", :write) {puts "foo.txt was modified!"}
queue.watch_process(, :fork, :exec) do |event|
  puts "This process has #{ {|f| f.to_s + "ed"}.join(" and ")}"

KQueue can monitor for all sorts of events. For a full list, see the watch_* methods on {Queue}.

Finally, run the queue:

This will loop infinitely, calling the appropriate callbacks when the events are fired. If you don't want infinite looping, you can also block until there are available events, process them all at once, and then continue on your merry way:



Bug Reports

They all go in the github issue tracker, no exception. (Well, the exception is when you have a patch, in that case, it goes into the github pull requests thingie.)

If you get a weird compilation error, it's most certainely a problem in ffi/ffi but do report it anyway so I can get a look at it.

Do get me the result of uname -a somewhere so that we know what OS and what version we're talking about.

Also, please, try to answer the following questions :

  • What did you do?
  • What did you expect to happen?
  • What happened instead?

Please also post code to replicate the bug. Ideally a failing test would be perfect, (one day there will be tests,) but even a simple script demonstrating the error would suffice. Please don't send me an entire application, unless the bug is in the interaction between rb-kqueue and a particular framework.

Make sure to specify which version of rb-kqueue you are using.

Pull Requests

  • Document any change in behaviour. Make sure the README and any other relevant documentation are kept up-to-date.

  • Consider our release cycle. We try to follow semver. Randomly breaking public APIs is not an option.

  • Create topic branches. Don't ask us to pull from your master branch.

  • One pull request per feature. If you want to do more than one thing, send multiple pull requests.

  • Send coherent history. Make sure each individual commit in your pull request is meaningful. If you had to make multiple intermediate commits while developing, please try to squash them before sending them to us. I quite like tpope's general guidelines, they're not absolute rules, but do try not to put all your commit message on the first line.

  • And if you feel like it, Add tests!, rspecs would be nice :-)

Something went wrong with that request. Please try again.