rev 0.1.1 → 0.1.2

data/ext/rev/rev_ext.c

@@ -26,4 +26,5 @@ void Init_rev_ext()
   Init_rev_watcher();
   Init_rev_io_watcher();
   Init_rev_timer_watcher();
+  Init_rev_buffer();
 }

data/ext/rev/rev_io_watcher.c

@@ -32,6 +32,13 @@ static VALUE Rev_IOWatcher_on_writable(VALUE self);
 static void Rev_IOWatcher_libev_callback(struct ev_loop *ev_loop, struct ev_io *io, int revents);
 static void Rev_IOWatcher_dispatch_callback(VALUE self, int revents);
 
+/*
+ * Rev::IOWatcher monitors Ruby IO objects for readability or writability.
+ * This allows your application to block while the kernel is writing out
+ * data and fill the read or write buffer whenever there is space available.
+ * It's used by the Rev::BufferedIO class to provide high performace I/O
+ * which is bound by the kernel's ability to read and write data.
+ */
 void Init_rev_io_watcher()
 {
   mRev = rb_define_module("Rev");
@@ -56,27 +63,27 @@ void Init_rev_io_watcher()
  */
 static VALUE Rev_IOWatcher_initialize(int argc, VALUE *argv, VALUE self)
 {
-	VALUE io, flags;
-	char *flags_str;
-	int events;
+  VALUE io, flags;
+  char *flags_str;
+  int events;
   rb_io_t *fptr;
   struct Rev_Watcher *watcher_data;
 
-	rb_scan_args(argc, argv, "11", &io, &flags);
-	
-	if(flags != Qnil)
-		flags_str = RSTRING_PTR(rb_String(flags));
-	else
-		flags_str = "r";
-		
-	if(!strcmp(flags_str, "r"))
-		events = EV_READ;
-	else if(!strcmp(flags_str, "w"))
-		events = EV_WRITE;
-	else if(!strcmp(flags_str, "rw"))
-		events = EV_READ | EV_WRITE;
-	else
-		rb_raise(rb_eArgError, "invalid event type: '%s' (must be 'r', 'w', or 'rw')", flags_str);
+  rb_scan_args(argc, argv, "11", &io, &flags);
+
+  if(flags != Qnil)
+    flags_str = RSTRING_PTR(rb_String(flags));
+  else
+    flags_str = "r";
+
+  if(!strcmp(flags_str, "r"))
+    events = EV_READ;
+  else if(!strcmp(flags_str, "w"))
+    events = EV_WRITE;
+  else if(!strcmp(flags_str, "rw"))
+    events = EV_READ | EV_WRITE;
+  else
+    rb_raise(rb_eArgError, "invalid event type: '%s' (must be 'r', 'w', or 'rw')", flags_str);
 
   GetOpenFile(rb_convert_type(io, T_FILE, "IO", "to_io"), fptr);
   Data_Get_Struct(self, struct Rev_Watcher, watcher_data);
@@ -85,9 +92,16 @@ static VALUE Rev_IOWatcher_initialize(int argc, VALUE *argv, VALUE self)
   ev_io_init(&watcher_data->event_types.ev_io, Rev_IOWatcher_libev_callback, fptr->fd, events);
   watcher_data->event_types.ev_io.data = (void *)self;
 
-	return Qnil;
+  return Qnil;
 }
 
+/**
+ *  call-seq:
+ *    Rev::IOWatcher.attach(loop) -> Rev::IOWatcher
+ * 
+ * Attach the IO watcher to the given Rev::Loop.  If the watcher is already attached
+ * to a loop, detach it from the old one and attach it to the new one.
+ */
 static VALUE Rev_IOWatcher_attach(VALUE self, VALUE loop)
 {
   Watcher_Attach(io, Rev_IOWatcher_detach, self, loop);
@@ -95,6 +109,12 @@ static VALUE Rev_IOWatcher_attach(VALUE self, VALUE loop)
   return self;  
 }
 
+/**
+ *  call-seq:
+ *    Rev::IOWatcher.detach -> Rev::IOWatcher
+ * 
+ * Detach the IO watcher from its current Rev::Loop.
+ */
 static VALUE Rev_IOWatcher_detach(VALUE self)
 {
   Watcher_Detach(io, self);
@@ -102,6 +122,13 @@ static VALUE Rev_IOWatcher_detach(VALUE self)
   return self;
 }
 
+/**
+ *  call-seq:
+ *    Rev::IOWatcher.enable -> Rev::IOWatcher
+ * 
+ * Re-enable an IO watcher which has been temporarily disabled.  See the
+ * disable method for a more thorough explanation.
+ */
 static VALUE Rev_IOWatcher_enable(VALUE self)
 {
   Watcher_Enable(io, self);
@@ -109,6 +136,13 @@ static VALUE Rev_IOWatcher_enable(VALUE self)
   return self;  
 }
 
+/**
+ *  call-seq:
+ *    Rev::IOWatcher.disable -> Rev::IOWatcher
+ * 
+ * Temporarily disable an IO watcher which is attached to a loop.  
+ * This is useful if you wish to toggle event monitoring on and off.  
+ */
 static VALUE Rev_IOWatcher_disable(VALUE self)
 {
   Watcher_Disable(io, self);

data/ext/rev/rev_loop.c

@@ -22,7 +22,7 @@ static void Rev_Loop_mark(struct Rev_Loop *loop);
 static void Rev_Loop_free(struct Rev_Loop *loop);
 
 /* Method implementations */
-static VALUE Rev_Loop_default(VALUE klass);
+static VALUE Rev_Loop_initialize(VALUE self);
 static VALUE Rev_Loop_ev_loop_new(VALUE self, VALUE flags);
 static VALUE Rev_Loop_run_once(VALUE self);
 static VALUE Rev_Loop_run_once_blocking(void *ptr);
@@ -32,18 +32,22 @@ static void Rev_Loop_dispatch_events(struct Rev_Loop *loop_data);
 
 #define DEFAULT_EVENTBUF_SIZE 32
 
+/* 
+ * Rev::Loop represents an event loop.  Event watchers can be attached and
+ * unattached.  When an event loop is run, all currently attached watchers
+ * are monitored for events, and their respective callbacks are signaled
+ * whenever events occur.
+ */
 void Init_rev_loop()
 {
   mRev = rb_define_module("Rev");
   cRev_Loop = rb_define_class_under(mRev, "Loop", rb_cObject);
   rb_define_alloc_func(cRev_Loop, Rev_Loop_allocate);
-  rb_define_singleton_method(cRev_Loop, "default", Rev_Loop_default, 0);
-
+ 
+  rb_define_method(cRev_Loop, "initialize", Rev_Loop_initialize, 0);
   rb_define_private_method(cRev_Loop, "ev_loop_new", Rev_Loop_ev_loop_new, 1);
   rb_define_method(cRev_Loop, "run_once", Rev_Loop_run_once, 0);
   rb_define_method(cRev_Loop, "run_nonblock", Rev_Loop_run_nonblock, 0);
-
-  rb_cv_set(cRev_Loop, "@@default_loop", Qnil);
 }
 
 static VALUE Rev_Loop_allocate(VALUE klass)
@@ -51,7 +55,6 @@ static VALUE Rev_Loop_allocate(VALUE klass)
   struct Rev_Loop *loop = (struct Rev_Loop *)xmalloc(sizeof(struct Rev_Loop));
 
   loop->ev_loop = 0;
-  loop->default_loop = 0;
 
   loop->events_received = 0;
   loop->eventbuf_size = DEFAULT_EVENTBUF_SIZE;
@@ -69,40 +72,15 @@ static void Rev_Loop_free(struct Rev_Loop *loop)
   if(!loop->ev_loop)
     return;
 
-  if(loop->default_loop)
-    ev_default_destroy();
-  else
-    ev_loop_destroy(loop->ev_loop);
+  ev_loop_destroy(loop->ev_loop);
 
   xfree(loop->eventbuf);
   xfree(loop);
 }
 
-
-/**
- *  call-seq:
- *    Rev::Loop.default -> Rev::Loop
- *
- * Retrieve a singleton instance of the default loop for the application
- */ 
-static VALUE Rev_Loop_default(VALUE klass)
+static VALUE Rev_Loop_initialize(VALUE self)
 {
-  struct Rev_Loop *loop_data;
-  VALUE default_loop = rb_cv_get(klass, "@@default_loop");
-
-  if(default_loop == Qnil) {
-    default_loop = rb_obj_alloc(klass);
-    Data_Get_Struct(default_loop, struct Rev_Loop, loop_data);
-
-    loop_data->ev_loop = ev_default_loop(0);
-    loop_data->default_loop = 1;
-
-    rb_cv_set(klass, "@@default_loop", default_loop);
-    rb_iv_set(default_loop, "@active_watchers", INT2NUM(0));
-    rb_iv_set(default_loop, "@watchers", rb_ary_new());
-  }
-
-  return default_loop;
+  Rev_Loop_ev_loop_new(self, INT2NUM(0));
 }
 
 /* Wrapper for populating a Rev_Loop struct with a new event loop */
@@ -115,7 +93,6 @@ static VALUE Rev_Loop_ev_loop_new(VALUE self, VALUE flags)
     rb_raise(rb_eRuntimeError, "loop already initialized");
 
   loop_data->ev_loop = ev_loop_new(NUM2INT(flags));
-  loop_data->default_loop = 0;
 
   return Qnil;
 }

data/ext/rev/rev_timer_watcher.c

@@ -31,6 +31,11 @@ static VALUE Rev_TimerWatcher_on_timer(VALUE self);
 static void Rev_TimerWatcher_libev_callback(struct ev_loop *ev_loop, struct ev_timer *timer, int revents);
 static void Rev_TimerWatcher_dispatch_callback(VALUE self, int revents);
 
+/*
+ * Rev::TimerWatcher lets you create either one-shot or periodic timers which
+ * run within Rev's event loop.  It's useful for creating timeouts or
+ * events which fire periodically.
+ */
 void Init_rev_timer_watcher()
 { 
   mRev = rb_define_module("Rev");
@@ -51,7 +56,11 @@ void Init_rev_timer_watcher()
  *  call-seq:
  *    Rev::TimerWatcher.initialize(interval, repeating = false) -> Rev::TimerWatcher
  * 
- * Create a new Rev::TimerWatcher for the given IO object and add it to the given Rev::Loop
+ * Create a new Rev::TimerWatcher for the given IO object and add it to the 
+ * given Rev::Loop.  Interval defines a duration in seconds to wait for events,
+ * and can be specified as an Integer or Float.  Repeating is a boolean 
+ * indicating whether the timer is one shot or should fire on the given 
+ * interval.
  */
 static VALUE Rev_TimerWatcher_initialize(int argc, VALUE *argv, VALUE self)
 {
@@ -59,16 +68,29 @@ static VALUE Rev_TimerWatcher_initialize(int argc, VALUE *argv, VALUE self)
   struct Rev_Watcher *watcher_data;
 
 	rb_scan_args(argc, argv, "11", &interval, &repeating);
-	
+  interval = rb_convert_type(interval, T_FLOAT, "Float", "to_f");
+
   Data_Get_Struct(self, struct Rev_Watcher, watcher_data);
 
   watcher_data->dispatch_callback = Rev_TimerWatcher_dispatch_callback;
-  ev_timer_init(&watcher_data->event_types.ev_timer, Rev_TimerWatcher_libev_callback, NUM2INT(interval), repeating == Qtrue);  
+  ev_timer_init(
+      &watcher_data->event_types.ev_timer, 
+      Rev_TimerWatcher_libev_callback, 
+      RFLOAT_VALUE(interval), 
+      repeating == Qtrue ? RFLOAT_VALUE(interval) : 0
+  );  
   watcher_data->event_types.ev_timer.data = (void *)self;
 
   return Qnil;
 }
 
+/**
+ *  call-seq:
+ *    Rev::TimerWatcher.attach(loop) -> Rev::TimerWatcher
+ * 
+ * Attach the timer watcher to the given Rev::Loop.  If the watcher is already
+ * attached to a loop, detach it from the old one and attach it to the new one.
+ */
 static VALUE Rev_TimerWatcher_attach(VALUE self, VALUE loop)
 {
   Watcher_Attach(timer, Rev_TimerWatcher_detach, self, loop);
@@ -76,6 +98,12 @@ static VALUE Rev_TimerWatcher_attach(VALUE self, VALUE loop)
   return self;  
 }
 
+/**
+ *  call-seq:
+ *    Rev::TimerWatcher.detach -> Rev::TimerWatcher
+ * 
+ * Detach the timer watcher from its current Rev::Loop.
+ */
 static VALUE Rev_TimerWatcher_detach(VALUE self)
 {
   Watcher_Detach(timer, self);
@@ -83,6 +111,13 @@ static VALUE Rev_TimerWatcher_detach(VALUE self)
   return self;
 }
 
+/**
+ *  call-seq:
+ *    Rev::TimerWatcher.enable -> Rev::TimerWatcher
+ * 
+ * Re-enable a timer watcher which has been temporarily disabled.  See the
+ * disable method for a more thorough explanation.
+ */
 static VALUE Rev_TimerWatcher_enable(VALUE self)
 {
   Watcher_Enable(timer, self);
@@ -90,6 +125,13 @@ static VALUE Rev_TimerWatcher_enable(VALUE self)
   return self;  
 }
 
+/**
+ *  call-seq:
+ *    Rev::TimerWatcher.disable -> Rev::TimerWatcher
+ * 
+ * Temporarily disable a timer watcher which is attached to a loop.  
+ * This is useful if you wish to toggle event monitoring on and off.  
+ */
 static VALUE Rev_TimerWatcher_disable(VALUE self)
 {
   Watcher_Disable(timer, self);

data/ext/rev/rev_watcher.c

@@ -30,6 +30,18 @@ static VALUE Rev_Watcher_evloop(VALUE self);
 static VALUE Rev_Watcher_attached(VALUE self);
 static VALUE Rev_Watcher_enabled(VALUE self);
 
+/* 
+ * Watchers are Rev's event observers.  They contain a set of callback
+ * methods prefixed by on_* which fire whenever events occur.
+ *
+ * In order for a watcher to fire events it must be attached to a running
+ * loop.  Every watcher has an attach and detach method to control which
+ * loop it's associated with.
+ *
+ * Watchers also have an enable and disable method.  This allows a watcher
+ * to temporarily ignore certain events while remaining attached to a given
+ * loop.  This is good for watchers which need to be toggled on and off.
+ */
 void Init_rev_watcher()
 {
   mRev = rb_define_module("Rev");
@@ -235,4 +247,4 @@ static VALUE Rev_Watcher_enabled(VALUE self)
   Data_Get_Struct(self, struct Rev_Watcher, watcher_data);
   
 	return watcher_data->enabled ? Qtrue : Qfalse;
-}
+}

data/lib/rev.rb

@@ -17,6 +17,6 @@ require File.dirname(__FILE__) + '/rev/server'
 require File.dirname(__FILE__) + '/rev/http_client'
 
 module Rev
-  Rev::VERSION = '0.1.1' unless defined? Rev::VERSION
+  Rev::VERSION = '0.1.2' unless defined? Rev::VERSION
   def self.version() VERSION end
 end

data/lib/rev/buffered_io.rb

@@ -7,13 +7,21 @@
 require File.dirname(__FILE__) + '/../rev'
 
 module Rev
+  # A buffered I/O class witch fits into the Rev Watcher framework.
+  # It provides both an observer which reads data as it's received
+  # from the wire and a buffered writer which stores data and writes
+  # it out each time the socket becomes writable.
+  #
+  # This class is primarily meant as a base class for other streams
+  # which need non-blocking writing, and is used to implement Rev's
+  # Socket class and its associated subclasses.
   class BufferedIO < IOWatcher
     # Maximum number of bytes to consume at once
     INPUT_SIZE = 16384
 
     def initialize(io)
       # Output buffer
-      @write_buffer = ''
+      @write_buffer = Rev::Buffer.new
 
       # Coerce the argument into an IO object if possible
       @io = IO.try_convert(io)
@@ -23,7 +31,7 @@ module Rev
     #
     # Callbacks for asynchronous events
     #
-
+      
     # Called whenever the IO object receives data
     def on_read(data); end
     event_callback :on_read
@@ -42,23 +50,7 @@ module Rev
 
     # Write data in a buffered, non-blocking manner
     def write(data)
-      # Attempt a zero copy write
-      if @write_buffer.empty?
-        written = write_nonblock data
-
-        # If we lucked out and wrote out the whole buffer, return
-        if written == data.size
-          on_write_complete
-          return data.size
-        end
-
-        # Otherwise slice what we wrote out and begin buffered writing
-        data.slice!(0, written) if written
-      end
-      
-      @write_buffer << data
-      schedule_write
-      data.size
+      buffered_write data
     end
 
     # Number of bytes are currently in the output buffer
@@ -73,19 +65,30 @@ module Rev
       @io.close unless @io.closed?
 
       on_close
+      nil
+    end
+
+    # Is the IO object closed?
+    def closed?
+      @io.closed?
     end
 
     #########
     protected
     #########
  
+    # Buffered writer
+    def buffered_write(data) 
+      @write_buffer << data
+      schedule_write
+      data.size
+    end
+
     # Attempt to write the contents of the output buffer
     def write_output_buffer
       return if @write_buffer.empty?
 
-      written = write_nonblock @write_buffer
-      @write_buffer.slice!(0, written) if written
-
+      @write_buffer.write_to(@io)
       return unless @write_buffer.empty?
 
       @writer.disable if @writer and @writer.enabled?

data/lib/rev/dns_resolver.rb

@@ -17,6 +17,17 @@ require File.dirname(__FILE__) + '/../rev'
 #++
 
 module Rev
+  # A non-blocking DNS resolver.  It provides interfaces for querying both
+  # /etc/hosts and nameserves listed in /etc/resolv.conf, or nameservers of
+  # your choosing.
+  #
+  # Presently the client only supports UDP requests against your nameservers
+  # and cannot resolve anything with records larger than 512-bytes.  Also,
+  # IPv6 is not presently supported.
+  #
+  # DNSResolver objects are one-shot.  Once they resolve a domain name they
+  # automatically detach themselves from the event loop and cannot be used
+  # again.
   class DNSResolver < IOWatcher
     RESOLV_CONF = '/etc/resolv.conf'
     HOSTS = '/etc/hosts'
@@ -25,9 +36,10 @@ module Rev
     TIMEOUT = 3 # Retry timeout for each datagram sent
     RETRIES = 4 # Number of retries to attempt
 
-    def self.hosts(host)
+    # Query /etc/hosts (or the specified hostfile) for the given host
+    def self.hosts(host, hostfile = HOSTS)
       hosts = {}
-      File.open(HOSTS).each_line do |host_entry|
+      File.open(hostfile).each_line do |host_entry|
         entries = host_entry.gsub(/#.*$/, '').gsub(/\s+/, ' ').split(' ')
         addr = entries.shift
         entries.each { |e| hosts[e] ||= addr }
@@ -36,6 +48,10 @@ module Rev
       hosts[host]
     end
 
+    # Create a new Rev::Watcher descended object to resolve the
+    # given hostname.  If you so desire you can also specify a
+    # list of nameservers to query.  By default the resolver will
+    # use nameservers listed in /etc/resolv.conf
     def initialize(hostname, *nameservers)
       if nameservers.empty?
         nameservers = File.read(RESOLV_CONF).scan(/^\s*nameserver\s+([0-9.:]+)/).flatten
@@ -44,30 +60,26 @@ module Rev
 
       @nameservers = nameservers
       @question = request_question hostname
-
+      
       @socket = UDPSocket.new
       @timer = Timeout.new(self)
       
       super(@socket)
     end
 
+    # Attach the DNSResolver to the given event loop
     def attach(evloop)
       send_request
       @timer.attach(evloop)
       super
     end
 
+    # Detach the DNSResolver from the given event loop
     def detach
       @timer.detach if @timer.attached?
       super
     end
 
-    # Send a request to the DNS server
-    def send_request
-      @socket.connect @nameservers.first, DNS_PORT
-      @socket.send request_message, 0
-    end
-
     # Called when the name has successfully resolved to an address
     def on_success(address); end
     event_callback :on_success
@@ -76,14 +88,19 @@ module Rev
     def on_failure; end
     event_callback :on_failure
 
-    # Called if we don't receive a response
-    def on_timeout; end
-    event_callback :on_timeout
+    # Called if we don't receive a response, defaults to on_failure
+    alias_method :on_timeout, :on_failure
 
     #########
     protected
     #########
 
+    # Send a request to the DNS server
+    def send_request
+      @socket.connect @nameservers.first, DNS_PORT
+      @socket.send request_message, 0
+    end
+
     # Called by the subclass when the DNS response is available
     def on_readable
       datagram = @socket.recvfrom_nonblock(DATAGRAM_SIZE).first
@@ -169,11 +186,11 @@ module Rev
 
       def on_timer
         @attempts += 1
-        return @resolver.send_request if @attempts <= RETRIES 
+        return @resolver.__send__(:send_request) if @attempts <= RETRIES 
 
         @resolver.__send__(:on_timeout)
         @resolver.detach
       end
     end
   end
-end
+end