sleepy_penguin 1.4.0 → 2.0.0

data/ext/sleepy_penguin/eventfd.c

@@ -1,19 +1,34 @@
 #ifdef HAVE_SYS_EVENTFD_H
 #include "sleepy_penguin.h"
 #include <sys/eventfd.h>
-#include "nonblock.h"
 static ID id_for_fd;
 
-static VALUE create(int argc, VALUE *argv, VALUE klass)
+/*
+ * call-seq:
+ *	EventFD.new(initial_value [, flags])	-> EventFD IO object
+ *
+ * Creates an EventFD object.  +initial_value+ is a non-negative Integer
+ * to start the internal counter at.
+ *
+ * Starting with Linux 2.6.27, +flags+ may be a mask that consists of any
+ * of the following:
+ *
+ * - :CLOEXEC - set the close-on-exec flag on the new object
+ * - :NONBLOCK - set the non-blocking I/O flag on the new object
+ *
+ * Since Linux 2.6.30, +flags+ may also include:
+ * - :SEMAPHORE - provides semaphore-like semantics (see EventFD#value)
+ */
+static VALUE s_new(int argc, VALUE *argv, VALUE klass)
 {
 	VALUE _initval, _flags;
 	unsigned initval;
-	int flags = 0;
+	int flags;
 	int fd;
 
 	rb_scan_args(argc, argv, "11", &_initval, &_flags);
 	initval = NUM2UINT(_initval);
-	flags = NIL_P(_flags) ? 0 : NUM2INT(_flags);
+	flags = rb_sp_get_flags(klass, _flags);
 
 	fd = eventfd(initval, flags);
 	if (fd == -1) {
@@ -28,7 +43,6 @@ static VALUE create(int argc, VALUE *argv, VALUE klass)
 	return rb_funcall(klass, id_for_fd, 1, INT2NUM(fd));
 }
 
-#ifdef HAVE_RB_THREAD_BLOCKING_REGION
 struct efd_args {
 	int fd;
 	uint64_t val;
@@ -37,7 +51,7 @@ struct efd_args {
 static VALUE efd_write(void *_args)
 {
 	struct efd_args *args = _args;
-	ssize_t w = write(args->fd, &args->buf, sizeof(uint64_t));
+	ssize_t w = write(args->fd, &args->val, sizeof(uint64_t));
 
 	return (VALUE)w;
 }
@@ -45,111 +59,80 @@ static VALUE efd_write(void *_args)
 static VALUE efd_read(void *_args)
 {
 	struct efd_args *args = _args;
-	ssize_t r = read(args->fd, &args->buf, sizeof(uint64_t));
+	ssize_t r = read(args->fd, &args->val, sizeof(uint64_t));
 
 	return (VALUE)r;
 }
 
-static VALUE incr(VALUE self, VALUE value)
+/*
+ * call-seq:
+ *	efd.incr(integer_value[, nonblock ])	-> true or nil
+ *
+ * Increments the internal counter by +integer_value+ which is an unsigned
+ * Integer value.
+ *
+ * If +nonblock+ is specified and true, this will return +nil+ if the
+ * internal counter will overflow the value of EventFD::MAX.
+ * Otherwise it will block until the counter may be incremented without
+ * overflowing.
+ */
+static VALUE incr(int argc, VALUE *argv, VALUE self)
 {
 	struct efd_args x;
 	ssize_t w;
+	VALUE value, nonblock;
 
-	x.fd = my_fileno(self);
+	rb_scan_args(argc, argv, "11", &value, &nonblock);
+	x.fd = rb_sp_fileno(self);
+	RTEST(nonblock) ? rb_sp_set_nonblock(x.fd) : blocking_io_prepare(x.fd);
 	x.val = (uint64_t)NUM2ULL(value);
-
 retry:
-	w = (ssize_t)rb_thread_blocking_region(efd_write, &x, RUBY_UBF_IO, 0);
+	w = (ssize_t)rb_sp_io_region(efd_write, &x);
 	if (w == -1) {
+		if (errno == EAGAIN && RTEST(nonblock))
+			return Qfalse;
 		if (rb_io_wait_writable(x.fd))
 			goto retry;
 		rb_sys_fail("write(eventfd)");
 	}
 
-	return Qnil;
+	return Qtrue;
 }
 
-static VALUE getvalue(VALUE self)
+/*
+ * call-seq:
+ *	efd.value([nonblock])	-> Integer or nil
+ *
+ * If not created as a semaphore, returns the current value and resets
+ * the counter to zero.
+ *
+ * If created as a semaphore, this decrements the counter value by one
+ * and returns +1+.
+ *
+ * If the counter is zero at the time of the call, this will block until
+ * the counter becomes non-zero unless +nonblock+ is +true+, in which
+ * case it returns +nil+.
+ */
+static VALUE getvalue(int argc, VALUE argv, VALUE self)
 {
 	struct efd_args x;
-
-	x.fd = my_fileno(self);
-
-retry:
-	w = (ssize_t)rb_thread_blocking_region(efd_read, &x, RUBY_UBF_IO, 0);
-	if (w == -1) {
-		if (rb_io_wait_readable(x.fd))
-			goto retry;
-		rb_sys_fail("read(eventfd)");
-	}
-
-	return ULL2NUM(x.buf);
-}
-#else  /* !HAVE_RB_THREAD_BLOCKING_REGION */
-
-static VALUE incr(VALUE self, VALUE value)
-{
-	int fd = my_fileno(self);
-	uint64_t val = (uint64_t)NUM2ULL(value);
 	ssize_t w;
+	VALUE nonblock;
 
-	set_nonblock(fd);
+	rb_scan_args(argc, argv, "01", &nonblock);
+	x.fd = rb_sp_fileno(self);
+	RTEST(nonblock) ? rb_sp_set_nonblock(x.fd) : blocking_io_prepare(x.fd);
 retry:
-	w = write(fd, &val, sizeof(uint64_t));
+	w = (ssize_t)rb_sp_io_region(efd_read, &x);
 	if (w == -1) {
-		if (rb_io_wait_writable(fd))
-			goto retry;
-		rb_sys_fail("write(eventfd)");
-	}
-
-	return Qnil;
-}
-
-static VALUE getvalue(VALUE self)
-{
-	int fd = my_fileno(self);
-	uint64_t val;
-	ssize_t r;
-
-	set_nonblock(fd);
-retry:
-	r = read(fd, &val, sizeof(uint64_t));
-	if (r == -1) {
-		if (rb_io_wait_readable(fd))
+		if (errno == EAGAIN && RTEST(nonblock))
+			return Qnil;
+		if (rb_io_wait_readable(x.fd))
 			goto retry;
 		rb_sys_fail("read(eventfd)");
 	}
 
-	return ULL2NUM(val);
-}
-#endif /* !HAVE_RB_THREAD_BLOCKING_REGION */
-
-static VALUE getvalue_nonblock(VALUE self)
-{
-	int fd = my_fileno(self);
-	uint64_t val;
-	ssize_t r;
-
-	set_nonblock(fd);
-	r = read(fd, &val, sizeof(uint64_t));
-	if (r == -1)
-		rb_sys_fail("read(eventfd)");
-
-	return ULL2NUM(val);
-}
-
-static VALUE incr_nonblock(VALUE self, VALUE value)
-{
-	int fd = my_fileno(self);
-	uint64_t val = (uint64_t)NUM2ULL(value);
-	ssize_t w;
-
-	set_nonblock(fd);
-	w = write(fd, &val, sizeof(uint64_t));
-	if (w == -1)
-		rb_sys_fail("write(eventfd)");
-
-	return Qnil;
+	return ULL2NUM(x.val);
 }
 
 void sleepy_penguin_init_eventfd(void)
@@ -157,21 +140,36 @@ void sleepy_penguin_init_eventfd(void)
 	VALUE mSleepyPenguin, cEventFD;
 
 	mSleepyPenguin = rb_define_module("SleepyPenguin");
+
+	/*
+	 * Document-class: SleepyPenguin::EventFD
+	 *
+	 * Applications may use EventFD instead of a pipe in cases where
+	 * a pipe is only used to signal events.  The kernel overhead for
+	 * an EventFD descriptor is much lower than that of a pipe.
+	 *
+	 * As of Linux 2.6.30, an EventFD may also be used as a semaphore.
+	 */
 	cEventFD = rb_define_class_under(mSleepyPenguin, "EventFD", rb_cIO);
-	rb_define_singleton_method(cEventFD, "new", create, -1);
+	rb_define_singleton_method(cEventFD, "new", s_new, -1);
+
+	/*
+	 * the maximum value that may be stored in an EventFD,
+	 * currently 0xfffffffffffffffe
+	 */
+	rb_define_const(cEventFD, "MAX", ULL2NUM(0xfffffffffffffffe));
+
 #ifdef EFD_NONBLOCK
-	rb_define_const(cEventFD, "NONBLOCK", UINT2NUM(EFD_NONBLOCK));
+	NODOC_CONST(cEventFD, "NONBLOCK", INT2NUM(EFD_NONBLOCK));
 #endif
 #ifdef EFD_CLOEXEC
-	rb_define_const(cEventFD, "CLOEXEC", UINT2NUM(EFD_CLOEXEC));
+	NODOC_CONST(cEventFD, "CLOEXEC", INT2NUM(EFD_CLOEXEC));
 #endif
 #ifdef EFD_SEMAPHORE
-	rb_define_const(cEventFD, "SEMAPHORE", UINT2NUM(EFD_SEMAPHORE));
+	NODOC_CONST(cEventFD, "SEMAPHORE", INT2NUM(EFD_SEMAPHORE));
 #endif
-	rb_define_method(cEventFD, "value", getvalue, 0);
-	rb_define_method(cEventFD, "incr", incr, 1);
-	rb_define_method(cEventFD, "value_nonblock", getvalue_nonblock, 0);
-	rb_define_method(cEventFD, "incr_nonblock", incr_nonblock, 1);
+	rb_define_method(cEventFD, "value", getvalue, -1);
+	rb_define_method(cEventFD, "incr", incr, -1);
 	id_for_fd = rb_intern("for_fd");
 }
 #endif /* HAVE_SYS_EVENTFD_H */

data/ext/sleepy_penguin/extconf.rb

@@ -5,6 +5,7 @@ have_header('sys/eventfd.h')
 have_header('sys/signalfd.h')
 have_header('sys/timerfd.h')
 have_header('sys/inotify.h')
+have_header('sys/signalfd.h')
 have_header('ruby/io.h') and have_struct_member('rb_io_t', 'fd', 'ruby/io.h')
 have_func('rb_memerror') or abort 'need rb_memerror()'
 have_func('rb_io_close') or abort 'need rb_io_close()'

data/ext/sleepy_penguin/init.c

@@ -18,10 +18,17 @@ void sleepy_penguin_init_inotify(void);
 #  define sleepy_penguin_init_inotify() for(;0;)
 #endif
 
+#ifdef HAVE_SYS_SIGNALFD_H
+void sleepy_penguin_init_signalfd(void);
+#else
+#  define sleepy_penguin_init_signalfd() for(;0;)
+#endif
+
 void Init_sleepy_penguin_ext(void)
 {
 	sleepy_penguin_init_epoll();
 	sleepy_penguin_init_timerfd();
 	sleepy_penguin_init_eventfd();
 	sleepy_penguin_init_inotify();
+	sleepy_penguin_init_signalfd();
 }

data/ext/sleepy_penguin/inotify.c

@@ -1,77 +1,32 @@
 #ifdef HAVE_SYS_INOTIFY_H
 #include "sleepy_penguin.h"
-#include "nonblock.h"
 #include <sys/inotify.h>
 #include <sys/ioctl.h>
+#include "missing_inotify.h"
+#if defined(RFILE) && defined(HAVE_ST_FD) && \
+    defined(HAVE_RB_THREAD_BLOCKING_REGION)
+#  define NOGVL_CLOSE
+#endif
+
 static ID id_for_fd, id_inotify_buf, id_inotify_tmp, id_mask;
 static VALUE cEvent, checks;
 
-#ifndef IN_CLOEXEC
-#  define IN_CLOEXEC 02000000
-#endif
-#ifndef IN_NONBLOCK
-#  define IN_NONBLOCK O_NONBLOCK
-#endif
-#ifndef IN_ATTRIB
-#  define IN_ATTRIB 0x00000004
-#endif
-#ifndef IN_ONLYDIR
-#  define IN_ONLYDIR 0x01000000
-#endif
-#ifndef IN_DONT_FOLLOW
-#  define IN_DONT_FOLLOW 0x02000000
-#endif
-#ifndef IN_EXCL_UNLINK
-#  define IN_EXCL_UNLINK 0x04000000
-#endif
-#ifndef IN_MASK_ADD
-#  define IN_MASK_ADD 0x20000000
-#endif
-#ifndef IN_ONESHOT
-#  define IN_ONESHOT 0x80000000
-#endif
-
-#ifndef HAVE_INOTIFY_INIT1
 /*
- * fake inotify_init1() since some systems don't have it
- * Don't worry about thread-safety since current Ruby 1.9 won't
- * call this without GVL.
+ * call-seq:
+ *	Inotify.new([flags])     -> Inotify IO object
+ *
+ * Flags may be any of the following as an Array of Symbols or Integer mask:
+ * - :NONBLOCK - sets the non-blocking flag on the descriptor watched.
+ * - :CLOEXEC - sets the close-on-exec flag
  */
-static int my_inotify_init1(int flags)
-{
-	int fd = inotify_init();
-	int tmp;
-
-	if (fd < 0)
-		return fd;
-	if ((flags & IN_CLOEXEC) && (fcntl(fd, F_SETFD, FD_CLOEXEC) == -1))
-		goto fcntl_err;
-	if (flags & IN_NONBLOCK) {
-		tmp = fcntl(fd, F_GETFL);
-		if (tmp == -1)
-			goto fcntl_err;
-		if ((fcntl(fd, F_SETFL, tmp | O_NONBLOCK) != 0))
-			goto fcntl_err;
-	}
-
-	return fd;
-fcntl_err:
-	tmp = errno;
-	close(fd);
-	errno = tmp;
-	rb_sys_fail("fcntl");
-}
-# define inotify_init1 my_inotify_init1
-#endif /* HAVE_INOTIFY_INIT1 */
-
-static VALUE s_init(int argc, VALUE *argv, VALUE klass)
+static VALUE s_new(int argc, VALUE *argv, VALUE klass)
 {
 	VALUE _flags, rv;
 	int flags;
 	int fd;
 
 	rb_scan_args(argc, argv, "01", &_flags);
-	flags = NIL_P(_flags) ? 0 : NUM2INT(_flags);
+	flags = rb_sp_get_flags(klass, _flags);
 
 	fd = inotify_init1(flags);
 	if (fd == -1) {
@@ -90,11 +45,51 @@ static VALUE s_init(int argc, VALUE *argv, VALUE klass)
 	return rv;
 }
 
+/*
+ * call-seq:
+ *	ino.add_watch(path, flags) -> Integer
+ *
+ * Adds a watch on an object specified by its +mask+, returns an unsigned
+ * Integer watch descriptor.  +flags+ may be a mask of the following
+ * Inotify constants or array of their symbolic names.
+ *
+ * - :ACCESS - File was accessed (read) (*)
+ * - :ATTRIB - Metadata changed.
+ * - :CLOSE_WRITE - File opened for writing was closed (*)
+ * - :CLOSE_NOWRITE - File not opened for writing was closed (*)
+ * - :CREATE - File/directory created in watched directory (*)
+ * - :DELETE - File/directory deleted from watched directory (*)
+ * - :DELETE_SELF - Watched file/directory was itself deleted
+ * - :MODIFY - File was modified (*)
+ * - :MOVE_SELF - Watched file/directory was itself moved
+ * - :MOVED_FROM - File moved out of watched directory (*)
+ * - :MOVED_TO - File moved into watched directory (*)
+ * - :OPEN - File was opened (*)
+ *
+ * When monitoring a directory, the events marked with an asterisk (*)
+ * above can occur for files in the directory, in which case the name
+ * field in the Event structure identifies the name of the file in the
+ * directory.
+ *
+ * Shortcut flags:
+ *
+ * - :ALL_EVENTS - a bitmask of all the above events
+ * - :MOVE - :MOVED_FROM or :MOVED_TO
+ * - :CLOSE - :CLOSE_WRITE or :CLOSE_NOWRITE
+ *
+ * The following watch attributes may also be included in flags:
+ *
+ * - :DONT_FOLLOW - don't dereference symlinks (since Linux 2.6.15)
+ * - :EXCL_UNLINK - don't generate unlink events for children (since 2.6.36)
+ * - :MASK_ADD - add events to an existing watch mask if it exists
+ * - :ONESHOT - monitor for one event and then remove it from the watch
+ * - :ONLYDIR - only watch the pathname if it is a directory
+ */
 static VALUE add_watch(VALUE self, VALUE path, VALUE vmask)
 {
-	int fd = my_fileno(self);
-	const char *pathname = StringValuePtr(path);
-	uint32_t mask = NUM2UINT(vmask);
+	int fd = rb_sp_fileno(self);
+	const char *pathname = StringValueCStr(path);
+	uint32_t mask = rb_sp_get_uflags(self, vmask);
 	int rc = inotify_add_watch(fd, pathname, mask);
 
 	if (rc == -1) {
@@ -108,10 +103,17 @@ static VALUE add_watch(VALUE self, VALUE path, VALUE vmask)
 	return UINT2NUM((uint32_t)rc);
 }
 
+/*
+ * call-seq:
+ *	ino.rm_watch(watch_descriptor) -> 0
+ *
+ * Removes a watch based on a watch descriptor Integer.  The watch
+ * descriptor is a return value given by Inotify#add_watch
+ */
 static VALUE rm_watch(VALUE self, VALUE vwd)
 {
 	uint32_t wd = NUM2UINT(vwd);
-	int fd = my_fileno(self);
+	int fd = rb_sp_fileno(self);
 	int rc = inotify_rm_watch(fd, wd);
 
 	if (rc == -1)
@@ -137,14 +139,32 @@ static VALUE event_new(struct inotify_event *e)
 	return rb_struct_new(cEvent, wd, mask, cookie, name);
 }
 
+struct inread_args {
+	int fd;
+	struct inotify_event *ptr;
+	long len;
+};
+
+static VALUE inread(void *ptr)
+{
+	struct inread_args *args = ptr;
+
+	return (VALUE)read(args->fd, args->ptr, args->len);
+}
+
+/*
+ * call-seq:
+ *	ino.take([nonblock]) -> Inotify::Event or nil
+ *
+ * Returns the next Inotify::Event processed.  May return +nil+ if +nonblock+
+ * is +true+.
+ */
 static VALUE take(int argc, VALUE *argv, VALUE self)
 {
-	int fd = my_fileno(self);
-	VALUE buf = rb_ivar_get(self, id_inotify_buf);
+	struct inread_args args;
+	VALUE buf;
 	VALUE tmp = rb_ivar_get(self, id_inotify_tmp);
-	struct inotify_event *ptr;
 	struct inotify_event *e, *end;
-	long len;
 	ssize_t r;
 	VALUE rv = Qnil;
 	VALUE nonblock;
@@ -154,31 +174,41 @@ static VALUE take(int argc, VALUE *argv, VALUE self)
 
 	rb_scan_args(argc, argv, "01", &nonblock);
 
-	len = RSTRING_LEN(buf);
-	ptr = (struct inotify_event *)RSTRING_PTR(buf);
+	args.fd = rb_sp_fileno(self);
+	buf = rb_ivar_get(self, id_inotify_buf);
+	args.len = RSTRING_LEN(buf);
+	args.ptr = (struct inotify_event *)RSTRING_PTR(buf);
+
+	if (RTEST(nonblock))
+		rb_sp_set_nonblock(args.fd);
+	else
+		blocking_io_prepare(args.fd);
 	do {
-		set_nonblock(fd);
-		r = read(fd, ptr, len);
-		if (r == 0 || (r < 0 && errno == EINVAL)) {
+		r = rb_sp_io_region(inread, &args);
+		if (r == 0 /* Linux < 2.6.21 */
+		    ||
+		    (r < 0 && errno == EINVAL) /* Linux >= 2.6.21 */
+		   ) {
+			/* resize internal buffer */
 			int newlen;
-			if (len > 0x10000)
+			if (args.len > 0x10000)
 				rb_raise(rb_eRuntimeError, "path too long");
-			if (ioctl(fd, FIONREAD, &newlen) != 0)
+			if (ioctl(args.fd, FIONREAD, &newlen) != 0)
 				rb_sys_fail("ioctl(inotify,FIONREAD)");
 			rb_str_resize(buf, newlen);
-			ptr = (struct inotify_event *)RSTRING_PTR(buf);
-			len = newlen;
+			args.ptr = (struct inotify_event *)RSTRING_PTR(buf);
+			args.len = newlen;
 		} else if (r < 0) {
-			if (errno == EAGAIN) {
-				if (RTEST(nonblock))
-					return Qnil;
-				rb_io_wait_readable(fd);
+			if (errno == EAGAIN && RTEST(nonblock)) {
+				return Qnil;
 			} else {
-				rb_sys_fail("read(inotify)");
+				if (!rb_io_wait_readable(args.fd))
+					rb_sys_fail("read(inotify)");
 			}
 		} else {
-			end = (struct inotify_event *)((char *)ptr + r);
-			for (e = ptr; e < end; ) {
+			/* buffer in userspace to minimize read() calls */
+			end = (struct inotify_event *)((char *)args.ptr + r);
+			for (e = args.ptr; e < end; ) {
 				VALUE event = event_new(e);
 				if (NIL_P(rv))
 					rv = event;
@@ -193,6 +223,13 @@ static VALUE take(int argc, VALUE *argv, VALUE self)
 	return rv;
 }
 
+/*
+ * call-seq:
+ *	inotify_event.events => [ :MOVED_TO, ... ]
+ *
+ * Returns an array of symbolic event names based on the contents of
+ * the +mask+ field.
+ */
 static VALUE events(VALUE self)
 {
 	long len = RARRAY_LEN(checks);
@@ -213,30 +250,132 @@ static VALUE events(VALUE self)
 	return rv;
 }
 
+/*
+ * call-seq:
+ *	inotify.dup	-> another Inotify object
+ *
+ * Duplicates an Inotify object, allowing it to be used in a blocking
+ * fashion in another thread.  Ensures duplicated Inotify objects do
+ * not share read buffers, but do share the userspace Array buffer.
+ */
 static VALUE init_copy(VALUE dest, VALUE orig)
 {
 	VALUE tmp;
 
-	dest = rb_call_super(1, &orig);
+	dest = rb_call_super(1, &orig); /* copy all other ivars as-is */
 	rb_ivar_set(dest, id_inotify_buf, rb_str_new(0, 128));
 
 	return dest;
 }
 
+/*
+ * call-seq:
+ *	ino.each { |event| ... } -> ino
+ *
+ * Yields each Inotify::Event received in a blocking fashion.
+ */
+static VALUE each(VALUE self)
+{
+	VALUE argv = Qfalse;
+
+	while (1)
+		rb_yield(take(0, &argv, self));
+
+	return self;
+}
+
+#if defined(NOGVL_CLOSE)
+static VALUE fptr_close(void *ptr)
+{
+	rb_io_t *fptr = ptr;
+	return (VALUE)close(fptr->fd);
+}
+
+/*
+ * call-seq:
+ *	ino.close	-> nil
+ *
+ * Closes the underlying file descriptor and releases resources used by the
+ * kernel.  Unlike other file descriptors, Inotify descriptors can take
+ * a long time to close(2).  Calling this explicitly releases the GVL under
+ * Ruby 1.9
+ */
+static VALUE nogvl_close(VALUE self)
+{
+	rb_io_t *fptr;
+
+	GetOpenFile(self, fptr);
+
+	if ((int)rb_sp_io_region(fptr_close, fptr) < 0)
+		rb_sys_fail("close(inotify)");
+	fptr->fd = -1;
+
+	return Qnil;
+}
+#endif /* NOGVL_CLOSE */
+
 void sleepy_penguin_init_inotify(void)
 {
 	VALUE mSleepyPenguin, cInotify;
 
 	mSleepyPenguin = rb_define_module("SleepyPenguin");
+
+	/*
+	 * Document-class: SleepyPenguin::Inotify
+	 *
+	 * Inotify objects are used for monitoring file system events,
+	 * it can monitor individual files or directories.  When a directory
+	 * is monitored it will return events for the directory itself and
+	 * all files inside the directory.
+	 *
+	 * Inotify IO objects can be watched using IO.select or Epoll.
+	 * IO#close may be called on the object when it is no longer needed.
+	 *
+	 * Inotify is available on Linux 2.6.13 or later.
+	 *
+	 *	require "sleepy_penguin/sp"
+	 *	ino = SP::Inotify.new
+	 *	ino.add_watch("/path/to/foo", :OPEN)
+	 *	ino.each do |event|
+	 *	  p event.events # => [ :OPEN ]
+	 *	end
+	 */
 	cInotify = rb_define_class_under(mSleepyPenguin, "Inotify", rb_cIO);
 	rb_define_method(cInotify, "add_watch", add_watch, 2);
 	rb_define_method(cInotify, "rm_watch", rm_watch, 1);
 	rb_define_method(cInotify, "initialize_copy", init_copy, 1);
 	rb_define_method(cInotify, "take", take, -1);
-	cEvent = rb_struct_define(NULL, "wd", "mask", "cookie", "name", NULL);
-	rb_define_const(cInotify, "Event", cEvent);
+	rb_define_method(cInotify, "each", each, 0);
+#ifdef NOGVL_CLOSE
+	rb_define_method(cInotify, "close", nogvl_close, 0);
+#endif
+
+	/*
+	 * Document-class: SleepyPenguin::Inotify::Event
+	 *
+	 * Returned by SleepyPenguin::Inotify#take.  It is a Struct with the
+	 * following elements:
+	 *
+	 * - wd   - watch descriptor (unsigned Integer)
+	 * - mask - mask of events (unsigned Integer)
+	 * - cookie - unique cookie associated related events (for rename)
+	 * - name - optional string name (may be nil)
+	 *
+	 * The mask is a bitmask of the event flags accepted by
+	 * Inotify#add_watch and may also include the following flags:
+	 *
+	 * - :IGNORED - watch was removed
+	 * - :ISDIR - event occured on a directory
+	 * - :Q_OVERFLOW - event queue overflowed (wd is -1)
+	 * - :UNMOUNT - filesystem containing watched object was unmounted
+	 *
+	 * Use the Event#events method to get an array of symbols for the
+	 * matched events.
+	 */
+	cEvent = rb_struct_define("Event", "wd", "mask", "cookie", "name", 0);
+	cEvent = rb_define_class_under(cInotify, "Event", cEvent);
 	rb_define_method(cEvent, "events", events, 0);
-	rb_define_singleton_method(cInotify, "new", s_init, -1);
+	rb_define_singleton_method(cInotify, "new", s_new, -1);
 	id_for_fd = rb_intern("for_fd");
 	id_inotify_buf = rb_intern("@inotify_buf");
 	id_inotify_tmp = rb_intern("@inotify_tmp");
@@ -251,8 +390,6 @@ void sleepy_penguin_init_inotify(void)
 	rb_ary_push(checks, val); \
 } while (0)
 
-	rb_define_const(cInotify, "FIONREAD", INT2NUM(FIONREAD));
-
 	IN(ALL_EVENTS);
 
 /* events a user can watch for */
@@ -287,7 +424,8 @@ void sleepy_penguin_init_inotify(void)
 	IN(ONESHOT);
 
 /* for inotify_init1() */
-	IN(NONBLOCK);
-	IN(CLOEXEC);
+
+	NODOC_CONST(cInotify, "NONBLOCK", INT2NUM(IN_NONBLOCK));
+	NODOC_CONST(cInotify, "CLOEXEC", INT2NUM(IN_CLOEXEC));
 }
 #endif /* HAVE_SYS_INOTIFY_H */