icmp4em 0.0.1 → 0.0.2

data/README

@@ -3,11 +3,13 @@ icmp4em - ICMP ping using EventMachine
 http://www.github.com/yakischloba/icmp4em
 
 Asynchronous implementation of ICMP ping using EventMachine. Can be used to ping many hosts 
-at once in a non-blocking fashion, with callbacks for success, timeout, and host failure/recovery 
+at once in a non-blocking (or blocking) fashion, with callbacks for success, timeout, and host failure/recovery 
 based on specified threshold numbers. It was developed as a component for the purpose of monitoring 
 multiple WAN connections on a Linux gateway host, and altering the routing table accordingly, to 
 provide optimal routing and failover in a situation where only consumer-grade broadband is available.
-Should be useful in many situations. ICMPv6 is to be added soon.
+Should be useful in many situations. Still planning on adding ICMPv6 sometime..
+
+Should work fine with Ruby 1.9.1.
 
 This must be run as effective root user to use the ICMP sockets.
 
@@ -40,7 +42,12 @@ Got echo sequence number 5 from host 127.0.0.1. It took 0.217ms.
 ^C
 ============================================================================
 
-Please let me know what is wrong with it!
+One issue may run into is that when using this with a lot of hosts, or using EventMachine for other things, 
+extra apparent latency will be added. This is simply due to other operations blocking the receipt of the ICMP 
+response. For when accurate latency measurement is important, and you can afford to block the reactor, I have 
+added a blocking receive mode. To use this simply pass :block => true to the constructor. This will wait for 
+the response for the duration of the timeout before passing control back to EventMachine.
+
 
 jakecdouglas@gmail.com
 yakischloba on Freenode
@@ -48,31 +55,6 @@ yakischloba on Freenode
 
 Thanks to the #eventmachine guys for providing a great tool and always being such patient teachers.
 
-Thanks to imperator and the others that worked on the net-ping library. I used the packet construction and checksum
-code from that implementation. Here is the pertinent information from their README, so that nothing is missed:
-
-Acknowledgements from "net-ping-1.2.2/doc/ping.txt": 
-
-= Acknowledgements
-   The Ping::ICMP#ping method is based largely on the identical method from
-   the Net::Ping Perl module by Rob Brown. Much of the code was ported by
-   Jos Backus on ruby-talk.
 
-= Future Plans
-   Add support for syn pings.
-
-= License
-   Ruby's
-
-= Copyright
-   (C) 2003-2008 Daniel J. Berger, All Rights Reserved
-
-= Warranty
-   This package is provided "as is" and without any express or
-   implied warranties, including, without limitation, the implied
-   warranties of merchantability and fitness for a particular purpose.
-
-= Author
-   Daniel J. Berger
-   djberg96 at gmail dot com
-   imperator on IRC (irc.freenode.net)
+Thanks to imperator and the others that worked on the net-ping library. I used the packet construction and checksum
+code from that implementation. See their README for detailed acknowledgements.

data/lib/icmp4em/common.rb

@@ -91,7 +91,6 @@ module ICMP4EM
           @expiry.call(@host, seq, reason)
         end
       end
-
     end
 
     # Executes specified failure callback, passing the host to the block.

data/lib/icmp4em/icmpv4.rb

@@ -11,15 +11,30 @@ module ICMP4EM
     class << self
       
       attr_reader :instances
-      attr_accessor :recvsocket
+      attr_accessor :recvsocket, :handler
       
     end
     
-    attr_accessor :bind_host, :interval, :threshold, :timeout, :data
+    attr_accessor :bind_host, :interval, :threshold, :timeout, :data, :block
     attr_reader :id, :failures_required, :recoveries_required, :seq
 
-    # Create a new ICMP object (host). Must be passed either IP address or hostname, and 
-    # optionally the interval at which it should be pinged, and timeout for the pings, in seconds.
+    # Create a new ICMP object (host). This takes a host and an optional hash of options for modifying the behavior. They are:
+    # * :bind_host
+    # Bind the socket to this address. The operating system will figure this out on it's own unless you need to set it for a special situation.
+    # * :timeout
+    # Timeout, in seconds, before the ping is considered expired and the appropriate callbacks are executed. This should be a numeric class.
+    # * :block
+    # True or false, default is false. True enables a blocking receive mode, for when accurate latency measurement is important. Due to the nature
+    # of event loop architecture, a noticable delay in latency can be added when other things are going on in the reactor.
+    # * :interval
+    # Interval, in seconds, for how often the ping should be sent. Should be a numeric class.
+    # * :stateful
+    # True or false, default is false. Indicates whether or not this ping object should keep track of it's successes and failures and execute
+    # the on_failure/on_recovery callbacks when the specified limits are hit.
+    # * :failures_required
+    # Indicates how many consequtive failures are required to switch to the 'failed' state and execute the on_failure callback. Applies only when :stateful => true
+    # * :recoveries_required
+    # Indicates how many consequtive successes are required to switch to the 'recovered' state and execute the on_recovery callback. Applies only when :stateful => true
     def initialize(host, options = {})
       raise 'requires root privileges' if Process.euid > 0
       @host = host
@@ -28,6 +43,7 @@ module ICMP4EM
       @timeout    =   options[:timeout] || 1
       @stateful   =   options[:stateful] || false
       @bind_host  =   options[:bind_host] || nil
+      @block      =   options[:block] || false
       @recoveries_required = options[:recoveries_required] || 5
       @failures_required   = options[:failures_required] || 5
       @up = true
@@ -38,9 +54,10 @@ module ICMP4EM
     end
     
     # This must be called when the object will no longer be used, to remove 
-    # the object from the class variable array that is searched for recipients when
-    # an ICMP echo comes in. Better way to do this whole thing?...
-    def destroy
+    # the object from the class variable hash that is searched for recipients when
+    # an ICMP echo comes in. Also cancels the periodic timer. Better way to do this whole thing?...
+    def stop
+      @ptimer.cancel if @ptimer
       self.class.instances[@id] = nil
     end
 
@@ -48,15 +65,19 @@ module ICMP4EM
     def ping
       raise "EM not running" unless EM.reactor_running?
       init_handler if self.class.recvsocket.nil?
-      seq = ping_send
-      EM.add_timer(@timeout) { self.send(:expire, seq, Timeout.new("Ping timed out")) } unless @timeout == 0
+      @seq = ping_send
+      if @block
+        blocking_receive
+      else
+        EM.add_timer(@timeout) { self.send(:expire, @seq, Timeout.new("Ping timed out")) } unless @timeout == 0
+      end
       @seq
     end
 
-    # Uses EM.add_periodic_timer to ping the host at @interval.
+    # Uses a periodic timer to ping the host at @interval.
     def schedule
       raise "EM not running" unless EM.reactor_running?
-      EM.add_periodic_timer(@interval) { self.ping }
+      @ptimer = EM::PeriodicTimer.new(@interval) { self.ping }
     end
 
     private
@@ -87,35 +108,27 @@ module ICMP4EM
 
     # Construct and send the ICMP echo request packet.
     def ping_send
-      @seq = (@seq + 1) % 65536
+      seq = (@seq + 1) % 65536
 
-      socket = Socket.new(
-      Socket::PF_INET,
-      Socket::SOCK_RAW,
-      Socket::IPPROTO_ICMP
-      )
-
-      if @bind_host
-        saddr = Socket.pack_sockaddr_in(0, @bind_host)
-        socket.bind(saddr)
-      end
+      socket = self.class.recvsocket
 
       # Generate msg with checksum
-      msg = [ICMP_ECHO, ICMP_SUBCODE, 0, @id, @seq, @data].pack("C2 n3 A*")
+      msg = [ICMP_ECHO, ICMP_SUBCODE, 0, @id, seq, @data].pack("C2 n3 A*")
       msg[2..3] = [generate_checksum(msg)].pack('n')
       
-      # Enqueue
+      # Enqueue so we can expire properly if there is an exception raised during #send
       @waiting[seq] = Time.now
       
       begin
         # Fire it off
         socket.send(msg, 0, @ipv4_sockaddr)
+        # Re-enqueue AFTER sendto() returns. This ensures we aren't adding latency if the socket blocks.
+        @waiting[seq] = Time.now
         # Return sequence number to caller
-        @seq
+        seq
       rescue Exception => err
-        expire(@seq, err)
-      ensure
-        socket.close if socket
+        expire(seq, err)
+        seq
       end
     end
 
@@ -130,7 +143,7 @@ module ICMP4EM
         saddr = Socket.pack_sockaddr_in(0, @bind_host)
         self.class.recvsocket.bind(saddr)
       end
-      EM.attach self.class.recvsocket, Handler, self.class.recvsocket
+      self.class.handler = EM.attach self.class.recvsocket, Handler, self.class.recvsocket
     end
 
     # Sets the instance id to a unique 16 bit integer so it can fit inside relevent the ICMP field.
@@ -144,6 +157,16 @@ module ICMP4EM
         end
       end
     end
+    
+    def blocking_receive
+      r = select([self.class.recvsocket], nil, nil, @timeout)
+      
+      if r and r.first.include?(self.class.recvsocket)
+        self.class.handler.notify_readable
+      else
+        expire(@seq, Timeout.new("Ping timed out"))
+      end
+    end
 
   end
   

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: icmp4em
 version: !ruby/object:Gem::Version 
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors: 
 - Jake Douglas
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-01-12 00:00:00 -08:00
+date: 2009-04-03 00:00:00 -07:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -38,7 +38,7 @@ files:
 - lib/icmp4em/common.rb
 - lib/icmp4em/handler.rb
 - lib/icmp4em/icmpv4.rb
-has_rdoc: false
+has_rdoc: true
 homepage: http://www.github.com/yakischloba/icmp4em
 post_install_message: 
 rdoc_options: []
@@ -60,7 +60,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 
 rubyforge_project: icmp4em
-rubygems_version: 1.2.0
+rubygems_version: 1.3.1
 signing_key: 
 specification_version: 2
 summary: Asynchronous implementation of ICMP ping using EventMachine