sinotify 0.0.2

data/ext/src/inotify.h

@@ -0,0 +1,113 @@
+/*
+ * Inode based directory notification for Linux
+ *
+ * Copyright (C) 2005 John McCutchan
+ */
+
+#ifndef _LINUX_INOTIFY_H
+#define _LINUX_INOTIFY_H
+
+#include <linux/types.h>
+
+/*
+ * struct inotify_event - structure read from the inotify device for each event
+ *
+ * When you are watching a directory, you will receive the filename for events
+ * such as IN_CREATE, IN_DELETE, IN_OPEN, IN_CLOSE, ..., relative to the wd.
+ */
+struct inotify_event {
+	__s32		wd;		/* watch descriptor */
+	__u32		mask;		/* watch mask */
+	__u32		cookie;		/* cookie to synchronize two events */
+	__u32		len;		/* length (including nulls) of name */
+	char		name[0];	/* stub for possible name */
+};
+
+/* the following are legal, implemented events that user-space can watch for */
+#define IN_ACCESS		0x00000001	/* File was accessed */
+#define IN_MODIFY		0x00000002	/* File was modified */
+#define IN_ATTRIB		0x00000004	/* Metadata changed */
+#define IN_CLOSE_WRITE		0x00000008	/* Writtable file was closed */
+#define IN_CLOSE_NOWRITE	0x00000010	/* Unwrittable file closed */
+#define IN_OPEN			0x00000020	/* File was opened */
+#define IN_MOVED_FROM		0x00000040	/* File was moved from X */
+#define IN_MOVED_TO		0x00000080	/* File was moved to Y */
+#define IN_CREATE		0x00000100	/* Subfile was created */
+#define IN_DELETE		0x00000200	/* Subfile was deleted */
+#define IN_DELETE_SELF		0x00000400	/* Self was deleted */
+#define IN_MOVE_SELF		0x00000800	/* Self was moved */
+
+/* the following are legal events.  they are sent as needed to any watch */
+#define IN_UNMOUNT		0x00002000	/* Backing fs was unmounted */
+#define IN_Q_OVERFLOW		0x00004000	/* Event queued overflowed */
+#define IN_IGNORED		0x00008000	/* File was ignored */
+
+/* helper events */
+#define IN_CLOSE		(IN_CLOSE_WRITE | IN_CLOSE_NOWRITE) /* close */
+#define IN_MOVE			(IN_MOVED_FROM | IN_MOVED_TO) /* moves */
+
+/* special flags */
+#define IN_ONLYDIR		0x01000000	/* only watch the path if it is a directory */
+#define IN_DONT_FOLLOW		0x02000000	/* don't follow a sym link */
+#define IN_MASK_ADD		0x20000000	/* add to the mask of an already existing watch */
+#define IN_ISDIR		0x40000000	/* event occurred against dir */
+#define IN_ONESHOT		0x80000000	/* only send event once */
+
+/*
+ * All of the events - we build the list by hand so that we can add flags in
+ * the future and not break backward compatibility.  Apps will get only the
+ * events that they originally wanted.  Be sure to add new events here!
+ */
+#define IN_ALL_EVENTS	(IN_ACCESS | IN_MODIFY | IN_ATTRIB | IN_CLOSE_WRITE | \
+			 IN_CLOSE_NOWRITE | IN_OPEN | IN_MOVED_FROM | \
+			 IN_MOVED_TO | IN_DELETE | IN_CREATE | IN_DELETE_SELF | \
+			 IN_MOVE_SELF)
+
+#ifdef __KERNEL__
+
+#include <linux/dcache.h>
+#include <linux/fs.h>
+#include <linux/config.h>
+
+#ifdef CONFIG_INOTIFY
+
+extern void inotify_inode_queue_event(struct inode *, __u32, __u32,
+				      const char *);
+extern void inotify_dentry_parent_queue_event(struct dentry *, __u32, __u32,
+					      const char *);
+extern void inotify_unmount_inodes(struct list_head *);
+extern void inotify_inode_is_dead(struct inode *);
+extern u32 inotify_get_cookie(void);
+
+#else
+
+static inline void inotify_inode_queue_event(struct inode *inode,
+					     __u32 mask, __u32 cookie,
+					     const char *filename)
+{
+}
+
+static inline void inotify_dentry_parent_queue_event(struct dentry *dentry,
+						     __u32 mask, __u32 cookie,
+						     const char *filename)
+{
+}
+
+static inline void inotify_unmount_inodes(struct list_head *list)
+{
+}
+
+static inline void inotify_inode_is_dead(struct inode *inode)
+{
+}
+
+static inline u32 inotify_get_cookie(void)
+{
+	return 0;
+}
+
+#endif	/* CONFIG_INOTIFY */
+
+#endif	/* __KERNEL __ */
+
+#endif	/* _LINUX_INOTIFY_H */

data/ext/src/sinotify.c

@@ -0,0 +1,205 @@
+#include <ruby.h>
+
+// includes that are different for ruby 1.8 vs. ruby 1.9
+#ifdef RUBY_19
+#warning "INCLUDING RUBY19 HEADERS (not really a warning, just for info)"
+#include <ruby/io.h>
+#else
+#warning "INCLUDING RUBY18 HEADERS (not really a warning, just for info) "
+#include <rubyio.h>
+
+#endif
+
+#ifdef HAVE_VERSION_H
+#include <version.h>
+#endif
+
+#ifdef HAVE_LINUX_INOTIFY_H
+#include <asm/unistd.h>
+#include <linux/inotify.h>
+#else
+#include "inotify.h"
+#include "inotify-syscalls.h"
+#endif
+
+#include <sys/syscall.h>
+#include <unistd.h>
+
+static inline int inotify_init (void)
+{
+	return syscall (__NR_inotify_init);
+}
+
+static inline int inotify_add_watch (int fd, const char *name, __u32 mask)
+{
+	return syscall (__NR_inotify_add_watch, fd, name, mask);
+}
+
+static inline int inotify_rm_watch (int fd, __u32 wd)
+{
+	return syscall (__NR_inotify_rm_watch, fd, wd);
+}
+
+VALUE rb_cSinotify;
+VALUE rb_cNotifier;
+VALUE rb_cSinotifyEvent;
+
+int event_check (int fd) {
+  struct timeval;
+	int r;
+
+	fd_set rfds;
+	FD_ZERO(&rfds);
+	FD_SET(fd, &rfds);
+
+  // Not using timout anymore
+	r = rb_thread_select (fd+1, &rfds, NULL, NULL, NULL);
+	return r;
+}
+
+static VALUE rb_inotify_event_new(struct inotify_event *event) {
+	VALUE retval;
+	retval = Data_Wrap_Struct(rb_cSinotifyEvent, NULL, free, event);
+	rb_obj_call_init(retval, 0, NULL);
+	return retval;
+}
+
+static VALUE rb_inotify_new(VALUE klass) {
+	int *fd;
+	VALUE retval;
+	fd = malloc(sizeof(int));
+	*fd = inotify_init();
+	if(*fd < 0) rb_sys_fail("inotify_init()");
+	retval = Data_Wrap_Struct(klass, NULL, free, fd);
+	rb_obj_call_init(retval, 0, NULL);
+	return retval;
+}
+
+static VALUE rb_inotify_add_watch(VALUE self, VALUE filename, VALUE mask) {
+	int *fd, wd;
+	Data_Get_Struct(self, int, fd);
+	wd = inotify_add_watch(*fd, RSTRING_PTR(filename), NUM2INT(mask));
+	if(wd < 0) {
+	  rb_sys_fail(RSTRING_PTR(filename));
+	}
+	return INT2NUM(wd);
+}
+
+static VALUE rb_inotify_rm_watch(VALUE self, VALUE wdnum) {
+	int *fd;
+	Data_Get_Struct(self, int, fd);
+	if(inotify_rm_watch(*fd, NUM2INT(wdnum)) < 0) {
+		rb_sys_fail("removing watch");
+	}
+	return Qtrue;
+}
+
+static VALUE rb_inotify_each_event(VALUE self) {
+	int *fd, r;
+	struct inotify_event *event, *pevent;
+	char buffer[16384];
+	size_t buffer_n, event_size;
+
+	Data_Get_Struct(self, int, fd);
+	while(1) {
+		r = event_check(*fd);
+		if(r == 0) {
+			continue;
+		}
+		if((r = read(*fd, buffer, 16384)) < 0) {
+			rb_sys_fail("reading event");
+		}
+		buffer_n = 0;
+		while (buffer_n < r) {
+			pevent = (struct inotify_event *)&buffer[buffer_n];
+			event_size = sizeof(struct inotify_event) + pevent->len;
+			event = malloc(event_size);
+			memmove(event, pevent, event_size);
+			buffer_n += event_size;
+			rb_yield(rb_inotify_event_new(event));
+		}
+	}
+	return Qnil;
+}
+
+static VALUE rb_inotify_close(VALUE self) {
+	int *fd;
+	Data_Get_Struct(self, int, fd);
+	if(close(*fd) != 0) {
+		rb_sys_fail("closing inotify");
+	}
+	return Qnil;
+}
+
+static VALUE rb_inotify_event_name(VALUE self) {
+	struct inotify_event *event;
+	Data_Get_Struct(self, struct inotify_event, event);
+	if(event->len) {
+		return rb_str_new2(event->name);
+	} else {
+		return Qnil;
+	}
+}
+
+static VALUE rb_inotify_event_wd(VALUE self) {
+	struct inotify_event *event;
+	Data_Get_Struct(self, struct inotify_event, event);
+	return INT2NUM(event->wd);
+}
+
+
+static VALUE rb_inotify_event_mask(VALUE self) {
+	struct inotify_event *event;
+	Data_Get_Struct(self, struct inotify_event, event);
+	return LONG2NUM(event->mask);
+}
+
+void Init_sinotify () {
+	rb_cSinotify = rb_define_module("Sinotify");
+
+  //
+  // The Sinotify::PrimNotifier class
+  //
+	rb_cNotifier = rb_define_class_under(rb_cSinotify, "PrimNotifier", rb_cObject);
+
+	rb_define_singleton_method(rb_cNotifier, "new", rb_inotify_new, 0);
+	rb_define_method(rb_cNotifier, "add_watch", rb_inotify_add_watch, 2);
+	rb_define_method(rb_cNotifier, "rm_watch", rb_inotify_rm_watch, 1);
+	rb_define_method(rb_cNotifier, "each_event", rb_inotify_each_event, 0);
+	rb_define_method(rb_cNotifier, "close", rb_inotify_close, 0);
+
+  //
+  // The Sinotify::PrimEvent class
+  //
+	rb_cSinotifyEvent = rb_define_class_under(rb_cSinotify, "PrimEvent", rb_cObject);
+	rb_define_method(rb_cSinotifyEvent, "prim_name", rb_inotify_event_name, 0);
+	rb_define_method(rb_cSinotifyEvent, "prim_wd", rb_inotify_event_wd, 0);
+	rb_define_method(rb_cSinotifyEvent, "prim_mask", rb_inotify_event_mask, 0);
+
+  // following inotify masks taken from inotify lib, see 'man inotify', section
+	rb_const_set(rb_cSinotifyEvent, rb_intern("ACCESS"), INT2NUM(IN_ACCESS));
+	rb_const_set(rb_cSinotifyEvent, rb_intern("MODIFY"), INT2NUM(IN_MODIFY));
+	rb_const_set(rb_cSinotifyEvent, rb_intern("ATTRIB"), INT2NUM(IN_ATTRIB));
+	rb_const_set(rb_cSinotifyEvent, rb_intern("CLOSE_WRITE"), INT2NUM(IN_CLOSE_WRITE));
+	rb_const_set(rb_cSinotifyEvent, rb_intern("CLOSE_NOWRITE"), INT2NUM(IN_CLOSE_NOWRITE));
+	rb_const_set(rb_cSinotifyEvent, rb_intern("OPEN"), INT2NUM(IN_OPEN));
+	rb_const_set(rb_cSinotifyEvent, rb_intern("MOVED_FROM"), INT2NUM(IN_MOVED_FROM));
+	rb_const_set(rb_cSinotifyEvent, rb_intern("MOVED_TO"), INT2NUM(IN_MOVED_TO));
+	rb_const_set(rb_cSinotifyEvent, rb_intern("CREATE"), INT2NUM(IN_CREATE));
+	rb_const_set(rb_cSinotifyEvent, rb_intern("DELETE"), INT2NUM(IN_DELETE));
+	rb_const_set(rb_cSinotifyEvent, rb_intern("DELETE_SELF"), INT2NUM(IN_DELETE_SELF));
+	rb_const_set(rb_cSinotifyEvent, rb_intern("MOVE_SELF"), INT2NUM(IN_MOVE_SELF));
+	rb_const_set(rb_cSinotifyEvent, rb_intern("UNMOUNT"), INT2NUM(IN_UNMOUNT));
+	rb_const_set(rb_cSinotifyEvent, rb_intern("Q_OVERFLOW"), INT2NUM(IN_Q_OVERFLOW));
+	rb_const_set(rb_cSinotifyEvent, rb_intern("IGNORED"), INT2NUM(IN_IGNORED));
+	rb_const_set(rb_cSinotifyEvent, rb_intern("CLOSE"), INT2NUM(IN_CLOSE));
+	rb_const_set(rb_cSinotifyEvent, rb_intern("MOVE"), INT2NUM(IN_MOVE));
+	rb_const_set(rb_cSinotifyEvent, rb_intern("ONLYDIR"), INT2NUM(IN_ONLYDIR));
+	rb_const_set(rb_cSinotifyEvent, rb_intern("DONT_FOLLOW"), INT2NUM(IN_DONT_FOLLOW));
+	rb_const_set(rb_cSinotifyEvent, rb_intern("MASK_ADD"), INT2NUM(IN_MASK_ADD));
+	rb_const_set(rb_cSinotifyEvent, rb_intern("ISDIR"), INT2NUM(IN_ISDIR));
+	rb_const_set(rb_cSinotifyEvent, rb_intern("ONESHOT"), INT2NUM(IN_ONESHOT));
+	rb_const_set(rb_cSinotifyEvent, rb_intern("ALL_EVENTS"), INT2NUM(IN_ALL_EVENTS));
+
+
+}

data/lib/sinotify.rb

@@ -0,0 +1,18 @@
+ext_lib = File.join(File.dirname(__FILE__), '../ext/sinotify.so')
+unless File.exist?(ext_lib)
+  raise "Could not find ext/sinotify.so. \n" \
+      + "Please build the sinotify.so extention first (cd [sinotify gem]/ext && ruby extconf.rb && make)" 
+end
+
+# load base info and c lib
+require ext_lib
+require File.join(File.dirname(__FILE__), 'sinotify_info')
+
+# load external dependencies
+require 'rubygems'
+require 'cosell'
+require 'logger'
+
+# load application
+Sinotify.require_all_libs_relative_to(__FILE__)
+

data/lib/sinotify/event.rb

@@ -0,0 +1,185 @@
+module Sinotify
+
+  # 
+  # Sinotify events are triggered as they come in to the Notifier ('announced'
+  # in the parlance of the Cosell announcement framework that sinotify uses).
+  # Each event has the 'path' of the file or dir that was effected, the
+  # timestamp of the event (generated in ruby, not at the primitive level), and
+  # whether the event was on a file or a directory. Also available is the event
+  # type, called the 'etype,' which can be :modify, :create, :delete, etc.  The
+  # list of event types is below. 
+  #
+  # A Sinotify::Event does not perfectly model a linux inotify event. See
+  # Sinotify::PrimEvent for that.
+  #
+  # This event class deviates from Sinotify::PrimEvent in one significant regard. Sinotify does not 
+  # pass events about children of a given directory, it only passes events about the directory 
+  # (or file) itself. That is _not_ to say you can't setup a recursive watch in the Notifier class,
+  # just that _the event itself_ only pertains the the inode/file/directory being altered, not to 
+  # its children. 
+  #
+  # This is perhaps best illustrated by an example. Let's say you
+  #
+  #   1. Create a directory called '/tmp/test'
+  #   2. Create a file in '/tmp/test' called '/tmp/test/blah'
+  #   3. You put a watch on the directory '/tmp/test'
+  #   4. You then do a 'rm -rf /tmp/test' 
+  #      (thus deleting both the file /tmp/test/blah AND the directory /tmp/test)
+  #
+  # In linux inotify, you would get two events in this scenario, _both_ on the
+  # watch for the /tmp/test directory. One of the events would be a ':delete' event
+  # (that is, the mask of the event would be equal to
+  # Sinotify::PrimEvent::DELETE, or the 'etype' of the PrimEvent would equal
+  # ':delete'), and the 'name' slot in the event would be 'blah.' This is your
+  # cue that the event _really_ happened on a child of the thing being watched
+  # ('/tmp/test'), not to the directory itself. Since you deleted both the file
+  # and the directory with your 'rm -rf' command, another event would come in
+  # of the etype :delete_self for the directory, and 'is_dir' would be in the
+  # mask (ie. the mask would be Sinotify::PrimEvent::DELETE & Sinotify::PrimEvent::IS_DIR). 
+  #
+  # Sinotify events would be a bit different in the example above.
+  # You would still get 2 events, but both would be :delete events, 
+  # one where the 'path' is '/tmp/test', and the other where the 'path'
+  # is '/tmp/test/blah'. In the case of the event for '/tmp/test', the call
+  # to 'directory?' would return true.
+  #
+  # If you want to work with an event notifier that works more like the low level linux inotify
+  # (receiving both :delete with name slot filled in and another event w/ :delete_self), 
+  # you will have to work directly with PrimNotifier and PrimEvent (along with their irritating 
+  # linux inotify-style blocking synchronous event loop)
+  #
+  # Here is the list of possible events adapted from the definitions
+  # in [linux_src]/include/linux/inotify.h: 
+  #
+  #   File related:
+  #     :access	# File was accessed 
+  #     :modify # file modified
+  #     :attrib # meta data changed
+  #     :close_write   # writable file was closed
+  #     :close_nowrite   # unwritable file was closed
+  #     :open  # file was opened
+  #     :moved_from # file moved from X
+  #     :moved_to  # file moved to Y
+  #     :create # file created
+  #     :delete # file deleted
+  #     :delete_self # self was deleted
+  #     :move_self  # self was moved
+  #
+  #  File related helpers:
+  #
+  #     :close  # (close_write | close_nowrite)
+  #     :move  # (moved_from | moved_to)
+  #
+  #  Misc events
+  #
+  #     :unmount # backing fs was unmounted
+  #     :q_overflow # event queue overflowed
+  #     :ignored  # file was ignored
+  #     :mask_add # added to mask of already existing event
+  #     :isdir # event occurred against dir
+  #     :oneshot # only send event once
+  #
+  class Event
+
+    attr_accessor :prim_event, :path, :timestamp, :is_dir
+
+    # a few attr declarations just so they show up in rdoc
+
+    # Given a prim_event, and the Watch associated with the event's watch descriptor,
+    # return a Sinotify::Event. 
+    def self.from_prim_event_and_watch(prim_event, watch)
+      path = watch.path         # path for the watch associated w/ this even
+      is_dir = watch.directory? # original watch was on a dir or a file?
+
+      # This gets a little odd. The prim_event's 'name' field
+      # will be nil if the change was to a directory itself, or if
+      # the watch was on a file to begin with. However,
+      # when a watch is on a dir, but the event occurs on a file in that dir
+      # inotify sets the 'name' field to the file. :isdir will be in the etypes
+      # if that file happens to be a subdir. Sinotify events do not
+      # play this game, only sending events for the thing that was altered
+      # in the first place. So right here is where we deduce if the 
+      # event was _really_ on a file or a dir.
+      unless prim_event.name.nil?
+        path = File.join(path, prim_event.name) 
+        is_dir = prim_event.etypes.include?(:isdir)
+      end
+
+      # is_dir must be passed along, since it may no longer exist (and thus cant be deduced later)
+      # inotify prim_events to not retain enough information to make it possible to deduce the
+      # original fullpath and whether it was a file or directory, so this info must be passed around.
+      return Sinotify::Event.new(:prim_event => prim_event,
+                                 :path => path,
+                                 :timestamp => Time.now, # any way to get this from prim event?
+                                 :is_dir => is_dir) 
+    end
+
+    def initialize(args={})
+      args.each{|k,v| self.send("#{k}=",v)}
+      @timestamp ||= Time.now
+
+      # initialize a few variables just to shut up the ruby warnings
+      @etypes = nil
+    end
+
+    # The Sinotify::PrimEvent associated with this event (a straight 
+    # wrapper around the linux inotify event)
+    def prim_event; @prim_event; end
+
+    # The full path of the file or directory on which the event happened
+    def path; @path; end
+
+    # when the event happened
+    def timestamp; @timestamp; end
+
+
+    def to_s; self.inspect_or_to_s(false); end
+    def inspect; self.inspect_or_to_s(true); end
+
+    # The etypes associated with this event (eg. :create, :modify, :delete, etc)
+    def etypes
+      # The etype/mask functions delegated to prim_event, EXCEPT: when :delete_self is in 
+      # the list, and path is a directory, change it to 'delete'. If you want
+      # the etypes in the original prim_event, ask for event.prim_event.etypes
+      if @etypes.nil?
+        @etypes = self.prim_event.etypes
+
+        # change :delete_self into :delete 
+        if self.directory? and @etypes.include?(:delete_self)
+          @etypes.delete(:delete_self)
+          @etypes << :delete
+        end
+
+        # add :close if :close_write or :close_nowrite are there, but :close is not
+        if @etypes.include?(:close_write) || @etypes.include?(:close_nowrite)
+          (@etypes << :close) unless @etypes.include?(:close)
+        end
+
+      end
+      @etypes
+    end
+
+    def directory?
+      self.is_dir.eql?(true)
+    end
+
+    def has_etype? etype
+      self.etypes.include?(etype)
+    end
+
+    def watch_descriptor
+      self.prim_event.watch_descriptor
+    end
+
+    protected
+
+      # :stopdoc:
+      def inspect_or_to_s(show_prim_event = false)
+        prim_event = (show_prim_event)? ", :prim_event => #{self.prim_event.inspect}" : ''
+        "<#{self.class} :path => '#{self.path}', dir? => #{self.directory?}, :etypes => #{self.etypes.inspect rescue 'could not determine'}#{prim_event}>"
+      end
+
+      # :startdoc:
+  end
+
+end