cztop-reactor 0.1.0.pre20170316155217

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 9ff9e9366325f56b5134fb0c8b7123c90b259709
+  data.tar.gz: f1effb0b47c1199772305b414d2f31e34bdb7798
+SHA512:
+  metadata.gz: 41e02a93aab2823b3dd3b6d05e2da1a15d873f99cf1efaa4068a7b632ee595b2641d0bda7a5d13b43eb931095235000edfb93a9daadb71d7517187530ffcdda6
+  data.tar.gz: 3e391f785107c50fa41f4a4bb761fc1ad14cef76411cb3bb52dfb61d58a952376294a0d9aa86f0c81487984e8f5d9bfb2e0b48a35d9c2b17dbd2e5a91180a006

data/.document

@@ -0,0 +1,5 @@
+lib/**/*.rb
+README.md
+ChangeLog.md
+
+LICENSE.txt

data/.rdoc_options

@@ -0,0 +1,16 @@
+--- !ruby/object:RDoc::Options
+encoding: UTF-8
+static_path: []
+rdoc_include:
+  - .
+charset: UTF-8
+exclude: 
+hyperlink_all: false
+line_numbers: false
+main_page: README.md
+markup: markdown
+show_hash: false
+tab_width: 8
+title: CZTop-Reactor Documentation
+visibility: :protected
+webcvs:

data/.simplecov

@@ -0,0 +1,9 @@
+# Simplecov config
+
+SimpleCov.start do
+	add_filter 'spec'
+	add_filter 'integration'
+	add_group "Needing tests" do |file|
+		file.covered_percent < 90
+	end
+end

data/ChangeLog

@@ -0,0 +1,30 @@
+2017-03-16  Michael Granger  <ged@FaerieMUD.org>
+
+	* .hgignore:
+	Ignore built gems
+	[594168b03b71] [tip]
+
+	* README.md:
+	Fix link in the README
+	[0391133d132d] [github/master]
+
+	* .hgignore:
+	Ignore generated docs directory
+	[ad4092564786]
+
+	* README.md:
+	Tabs -> spaces in the README
+	[41ec0ff65005]
+
+	* cztop-reactor.gemspec:
+	Add generated gemspec
+	[b3fcff597575]
+
+	* .document, .editorconfig, .gems, .hgignore, .hoerc, .pryrc,
+	.rdoc_options, .ruby-gemset, .ruby-version, .simplecov, Gemfile,
+	History.md, LICENSE.txt, Manifest.txt, README.md, Rakefile,
+	certs/ged.pem, lib/cztop/reactor.rb, lib/cztop/reactor/event.rb,
+	spec/cztop/reactor/event_spec.rb, spec/cztop/reactor_spec.rb,
+	spec/spec_helper.rb:
+	Initial commit.
+	[5e3f2358036b]

data/History.md

@@ -0,0 +1,4 @@
+## v0.0.1 [YYYY-MM-DD] Michael Granger <ged@FaerieMUD.org>
+
+Initial release.
+

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2017 Michael Granger
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Manifest.txt

@@ -0,0 +1,14 @@
+.document
+.rdoc_options
+.simplecov
+ChangeLog
+History.md
+LICENSE.txt
+Manifest.txt
+README.md
+Rakefile
+lib/cztop/reactor.rb
+lib/cztop/reactor/event.rb
+spec/cztop/reactor/event_spec.rb
+spec/cztop/reactor_spec.rb
+spec/spec_helper.rb

data/README.md

@@ -0,0 +1,113 @@
+# CZTop-Reactor
+
+home
+: http://deveiate.org/projects/CZTop-Reactor
+
+code
+: http://bitbucket.org/ged/cztop-reactor
+
+github
+: https://github.com/ged/cztop-reactor
+
+docs
+: http://deveiate.org/code/cztop-reactor
+
+
+## Description
+
+This is an implementation of the Reactor pattern described in [Pattern-Oriented
+Software Architecture (Volume 2)][POSA2]. It allows an asynchronous application
+to be described as one or more "reactions" to events, in this case either I/O
+conditions on a ZMQ socket or a timer expiring.
+
+A simple example:
+
+    # Start a SERVER socket, and print out any messages sent to it
+    reactor = CZTop::Reactor.new
+    socket = CZTop::Socket::SERVER.new
+    socket.bind( 'tcp://0.0.0.0:8' )
+    reactor.register( socket, :read ) do |event|
+      if event.readable?
+        message = event.socket.receive
+        puts "Read: %p" % [ message.to_a ]
+      end
+    end
+    reactor.start_polling
+
+
+## Prerequisites
+
+It should run under any Ruby interpreter that CZTop will, which at the time of
+this writing includes:
+
+* MRI (2.3, 2.2)
+* Rubinius (HEAD)
+* JRuby 9000 (HEAD)
+
+I am also using it (and CZTop) under MRI 2.4.
+
+
+## Installation
+
+    $ gem install cztop-reactor
+
+
+## Reasons
+
+I considered submitting this as a patch to `cztop`, but in the end elected to
+distribute it as a gem for two reasons:
+
+1. It depends on the `timers` gem, and I didn't want to add this dependency to
+   `cztop`. If the [`ztimerset`][ztimerset] spec ever comes out of draft status
+   and `cztop` adds an implementation of it, this wouldn't be necessary.
+2. I'm not confident enough in my FFI knowledge to know if this is an
+   appropriate way to implement this class. I've written numerous C extensions 
+   for Ruby, but FFI is still a bit of a mystery to me, and likely will remain 
+   so for the foreseeable future given my misgivings about using it.
+
+
+## Contributing
+
+You can check out the current development source with Mercurial via its
+{project page}[http://bitbucket.org/ged/cztop-reactor]. Or if you prefer Git,
+via {its Github mirror}[https://github.com/ged/cztop-reactor].
+
+After checking out the source, run:
+
+    $ rake newb
+
+This task will install any missing dependencies, run the tests/specs,
+and generate the API documentation.
+
+
+## License
+
+This library includes source from the CZTop gem by Patrik Wenger, which is
+distributed under the terms of the [ISC
+License](http://opensource.org/licenses/ISC):
+
+> Copyright (c) 2016, Patrik Wenger
+>
+> Permission to use, copy, modify, and/or distribute this software for
+> any purpose with or without fee is hereby granted, provided that
+> the above copyright notice and this permission notice appear in all
+> copies.
+>
+> THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL
+> WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED
+> WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE
+> AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL
+> DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA
+> OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
+> TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+> PERFORMANCE OF THIS SOFTWARE.
+
+Everything else is distributed under the same license but is:
+
+Copyright (c) 2017, Michael Granger
+
+
+[POSA2]: http://www.cs.wustl.edu/~schmidt/POSA/POSA2/
+[ztimerset]: http://czmq.zeromq.org/czmq4-0:ztimerset
+
+

data/Rakefile

@@ -0,0 +1,100 @@
+#!/usr/bin/env rake
+
+begin
+	require 'hoe'
+rescue LoadError
+	abort "This Rakefile requires hoe (gem install hoe)"
+end
+
+GEMSPEC = 'cztop-reactor.gemspec'
+
+
+Hoe.plugin :mercurial
+Hoe.plugin :signing
+Hoe.plugin :deveiate
+
+Hoe.plugins.delete :rubyforge
+Hoe.plugins.delete :gemcutter # Remove for public gems
+
+hoespec = Hoe.spec 'cztop-reactor' do |spec|
+	self.readme_file = 'README.md'
+	self.history_file = 'History.md'
+	self.extra_rdoc_files = FileList[ '*.rdoc', '*.md' ]
+	self.urls = {
+		home:   'http://deveiate.org/projects/cztop-reactor',
+		code:   'http://bitbucket.org/ged/cztop-reactor',
+		docs:   'http://deveiate.org/code/cztop-reactor',
+		github: 'http://github.com/ged/cztop-reactor',
+	}
+
+	spec.license 'ISC'
+
+	spec.developer 'Michael Granger', 'ged@FaerieMUD.org'
+
+	spec.dependency 'loggability', '~> 0.14'
+	spec.dependency 'cztop', '~> 0.11'
+	spec.dependency 'timers', '~> 4.1'
+
+	spec.dependency 'hoe-deveiate',            '~> 0.9', :developer
+	spec.dependency 'simplecov',               '~> 0.13', :developer
+	spec.dependency 'rdoc-generator-fivefish', '~> 0.3', :developer
+
+	spec.require_ruby_version( '>=2.2.4' )
+	spec.hg_sign_tags = true if spec.respond_to?( :hg_sign_tags= )
+	spec.check_history_on_release = true if spec.respond_to?( :check_history_on_release= )
+
+	self.rdoc_locations << "deveiate:/usr/local/www/public/code/#{remote_rdoc_dir}"
+end
+
+
+ENV['VERSION'] ||= hoespec.spec.version.to_s
+
+# Run the tests before checking in
+task 'hg:precheckin' => [ :check_history, :check_manifest, :gemspec, :spec ]
+
+task :test => :spec
+
+# Rebuild the ChangeLog immediately before release
+task :prerelease => 'ChangeLog'
+CLOBBER.include( 'ChangeLog' )
+
+desc "Build a coverage report"
+task :coverage do
+	ENV["COVERAGE"] = 'yes'
+	Rake::Task[:spec].invoke
+end
+CLOBBER.include( 'coverage' )
+
+
+# Use the fivefish formatter for docs generated from development checkout
+if File.directory?( '.hg' )
+	require 'rdoc/task'
+
+	Rake::Task[ 'docs' ].clear
+	RDoc::Task.new( 'docs' ) do |rdoc|
+		rdoc.markup = 'markdown'
+		rdoc.main = "README.md"
+		rdoc.rdoc_files.include( "*.md", "ChangeLog", "lib/**/*.rb" )
+
+		rdoc.generator = :fivefish
+		rdoc.title = 'CZTop-Reactor'
+		rdoc.rdoc_dir = 'doc'
+	end
+end
+
+task :gemspec => GEMSPEC
+file GEMSPEC => __FILE__
+task GEMSPEC do |task|
+	spec = $hoespec.spec
+	spec.files.delete( '.gemtest' )
+	spec.signing_key = nil
+	spec.cert_chain = ['certs/ged.pem']
+	spec.version = "#{spec.version.bump}.0.pre#{Time.now.strftime("%Y%m%d%H%M%S")}"
+	File.open( task.name, 'w' ) do |fh|
+		fh.write( spec.to_ruby )
+	end
+end
+CLOBBER.include( GEMSPEC.to_s )
+
+task :default => :gemspec
+

data/lib/cztop/reactor.rb

@@ -0,0 +1,350 @@
+# -*- ruby -*-
+#encoding: utf-8
+
+require 'loggability'
+require 'timers'
+require 'ffi'
+
+require 'cztop'
+require 'cztop/poller'
+require 'cztop/has_ffi_delegate'
+
+
+# An implementation of the Reactor pattern described in
+# [Pattern-Oriented Software Architecture (Volume 2)][POSA2]. It allows
+# an asynchronous application to be described as one or more "reactions"
+# to events, in this case either I/O conditions on a ZMQ socket or a
+# timer expiring.
+#
+# [POSA2]: http://www.cs.wustl.edu/~schmidt/POSA/POSA2/
+#
+class CZTop::Reactor
+	extend Loggability
+
+	# The version of this library
+	VERSION = '0.0.1'
+
+	# The maximum number of seconds to wait for events when there are no timers
+	# registered.
+	DEFAULT_POLL_INTERVAL = 0.250
+
+	# The events that can be registered and the corresponding mask
+	VALID_EVENTS = {
+		 read: CZTop::Poller::ZMQ::POLLIN,
+		write: CZTop::Poller::ZMQ::POLLOUT,
+	}.freeze
+
+
+	autoload :Event, 'cztop/reactor/event'
+
+
+	# Loggability API -- set up a logger for this class
+	log_as :cztop
+
+
+	### Create a new CZTop::Reactor
+	def initialize
+		@sockets = Hash.new do |hsh,key|
+			hsh[ key ] = { events: [], handler: nil }
+		end
+		@timers = Timers::Group.new
+		@wakeup_timer = @timers.every( DEFAULT_POLL_INTERVAL ) do
+			# No-op -- just ensures that new timers that are registered are only
+			# delayed by (at most) the DEFAULT_POLL_INTERVAL before they start.
+		end
+
+		@socket_pointers = {}
+
+		@poller_ptr = CZTop::Poller::ZMQ.poller_new
+		ObjectSpace.define_finalizer( @poller_ptr, -> (obj_id) {
+			# $stderr.puts "Freeing the poller pointer %p" % [ @poller_ptr ]
+			ptr_ptr = ::FFI::MemoryPointer.new( :pointer )
+			ptr_ptr.write_pointer( @poller_ptr )
+			CZTop::Poller::ZMQ.poller_destroy( ptr_ptr )
+		})
+		@event_ptr = ::FFI::MemoryPointer.new( CZTop::Poller::ZMQ::PollerEvent )
+	end
+
+
+	######
+	public
+	######
+
+	##
+	# Sockets and the handlers that handle their IO
+	attr_reader :sockets
+
+	##
+	# Registered timers as a Timers::Group
+	attr_reader :timers
+
+	##
+	# The handle of the default timer that is used to ensure the polling loop
+	# notices new sockets and timers.
+	attr_reader :wakeup_timer
+
+
+	#
+	# Sockets
+	#
+
+	### Register the specified +socket+ with the reactor for the specified +events+.
+	### The following events are supported:
+	###
+	### [<tt>:read</tt>]
+	###   Data may be read from the socket without blocking.
+	### [<tt>:write</tt>]
+	###   Data may be written to the socket without blocking.
+	###
+	### Registering a handle will unregister any previously registered
+	### event/handler+arguments pairs associated with the handle.
+	###
+	def register( socket, *events, &handler )
+		raise LocalJumpError, "no handler given" unless handler
+
+		self.unregister( socket )
+
+		ptr = self.ptr_for_socket( socket )
+		rc = CZTop::Poller::ZMQ.poller_add( @poller_ptr, ptr, nil, 0 )
+		self.log.debug "poller_add: rc = %p" % [ rc ]
+		CZTop::HasFFIDelegate.raise_zmq_err if rc == -1
+
+		self.log.info "Registered: %p with handler: %p" % [ socket, handler ]
+		self.sockets[ socket ][ :handler ] = handler
+		self.enable_events( socket, *events )
+
+		@socket_pointers[ ptr.to_i ] = socket
+	end
+	alias_method :add, :register
+	alias_method :register_socket, :register
+
+
+	### Remove the specified <tt>socket</tt> from the receiver's list of registered
+	### handles, if present. Returns the handle if it was registered, or
+	### <tt>nil</tt> if it was not.
+	def unregister( socket )
+		if self.sockets.delete( socket )
+			self.log.info "Unregistering: %p" % [ socket ]
+			ptr = self.ptr_for_socket( socket )
+			rc = CZTop::Poller::ZMQ.poller_remove( @poller_ptr, ptr )
+			self.log.debug "poller_remove: rc = %p" % [ rc ]
+			CZTop::HasFFIDelegate.raise_zmq_err if rc == -1
+		end
+
+		@socket_pointers.delete( ptr.to_i )
+	end
+	alias_method :remove, :unregister
+	alias_method :unregister_socket, :unregister
+
+
+	### Returns +true+ if the given +socket+ handle is registered with the reactor.
+	def registered?( socket )
+		return self.sockets.key?( socket )
+	end
+
+
+	### Add the specified +events+ to the list that will be polled for on the
+	### given +socket+.
+	def enable_events( socket, *events )
+		invalid = events - ( events & VALID_EVENTS.keys )
+		if !invalid.empty?
+			raise ArgumentError, "invalid events: %p" % [ invalid ]
+		end
+
+		socket = self.socket_for_ptr( socket ) if socket.is_a?( FFI::Pointer )
+		raise ArgumentError, "%p is not registered yet" % [ socket ] unless
+			self.registered?( socket )
+
+		self.sockets[ socket ][ :events ] |= events
+		self.update_poller_for( socket )
+	end
+	alias_method :enable_event, :enable_events
+	alias_method :enable_socket_events, :enable_events
+	alias_method :enable_socket_event, :enable_events
+
+
+	### Remove the specified +events+ from the list that will be polled for on
+	### the given +socket+ handle.
+	def disable_events( socket, *events )
+		socket = self.socket_for_ptr( socket ) if socket.is_a?( FFI::Pointer )
+		self.sockets[ socket ][:events] -= events
+		self.update_poller_for( socket )
+	end
+	alias_method :disable_socket_events, :disable_events
+
+
+	### Returns +true+ if the specified +event+ is enabled for the given +socket+.
+	def event_enabled?( socket, event )
+		socket = self.socket_for_ptr( socket ) if socket.is_a?( FFI::Pointer )
+
+		return false unless self.sockets.key?( socket )
+		return self.sockets[ socket ][ :events ].include?( event )
+	end
+	alias_method :has_event_enabled?, :event_enabled?
+	alias_method :socket_event_enabled?, :event_enabled?
+
+
+	### Returns <tt>true</tt> if no sockets are registered.
+	def empty?
+		return self.sockets.empty? && self.timers.empty?
+	end
+
+
+	### Clear all registered sockets and returns the sockets that were cleared.
+	def clear
+		sockets = self.sockets.keys
+		sockets.each {|sock| self.unregister(sock) }
+		return sockets
+	end
+
+
+	#
+	# Timers
+	#
+
+	### Register a timer that will call the specified +callback+ once after +delay+
+	### seconds.
+	def add_oneshot_timer( delay, &callback )
+		self.log.debug "Registering a oneshot timer: will call %p after %0.2fs" %
+			[ callback, delay ]
+		return self.timers.after( delay, &callback )
+	end
+
+
+	### Register a timer that will call the specified +callback+ once every
+	### +delay+ seconds until it is cancelled.
+	def add_periodic_timer( delay, &callback )
+		self.log.debug "Registering a periodic timer: will call %p every %0.2fs" %
+			[ callback, delay ]
+		return self.timers.every( delay, &callback )
+	end
+
+
+	### Remove the specified +timer+ from the reactor.
+	def remove_timer( timer )
+		timer.cancel
+	end
+
+
+	#
+	# Monitors
+	#
+
+	### Create a CZTop::Monitor for the specified +socket+ that will listen for the
+	### specified +events+ (which are monitor events, not I/O events). It will be automatically
+	### registered with the reactor for the `:read` event with the specified +callback+,
+	### then returned.
+	def register_monitor( socket, *events, &callback )
+		events.push( 'ALL' ) if events.empty?
+
+		monitor = CZTop::Monitor.new( socket )
+		monitor.listen( *events )
+		monitor.start
+
+		self.register( monitor.actor, :read, &callback )
+
+		return monitor
+	end
+	alias_method :start_monitor, :register_monitor
+
+
+
+	#
+	# Polling
+	#
+
+	### Poll the sockets registered to the reactor for pending events.
+	def start_polling
+		until self.empty?
+			self.log.debug "Polling %d sockets" % [ self.sockets.length ]
+
+			wait_interval = self.timers.wait_interval || DEFAULT_POLL_INTERVAL
+
+			# If there's a timer already due to fire, don't wait at all
+			event = if wait_interval > 0
+					self.log.debug "Waiting for IO for %fms" % [ wait_interval * 1000 ]
+					self.wait( wait_interval * 1000 )
+				else
+					nil
+				end
+
+			self.log.debug "Got event %p" % [ event ]
+			if event
+				# self.log.debug "Got event: %p" % [ event ]
+				handler = self.sockets[ event.socket ][ :handler ]
+				handler.call( event ) if handler
+			else
+				self.log.debug "Expired: firing timers."
+				self.timers.fire
+			end
+
+			self.log.debug "%d sockets after polling: %p" % [ self.sockets.length, self.sockets ]
+		end
+	end
+
+
+	### Stop polling for events and prepare to shut down.
+	def stop_polling
+		self.log.debug "Stopping the poll loop."
+		self.clear
+		self.timers.cancel
+	end
+
+
+	### Return the socket object for the given +pointer+ (an FFI::Pointer), or +nil+ if the
+	### pointer is unknown.
+	def socket_for_ptr( pointer )
+		return @socket_pointers[ pointer.to_i ]
+	end
+
+
+	#########
+	protected
+	#########
+
+	### Waits for events on registered sockets. Returns the first such event, or +nil+ if
+	### no events arrived within the specified +timeout+. If +timeout+ is -1, wait
+	### indefinitely.
+	def wait( timeout=-1 )
+		rc = CZTop::Poller::ZMQ.poller_wait( @poller_ptr, @event_ptr, timeout )
+		if rc == -1
+			if CZMQ::FFI::Errors.errno != Errno::ETIMEDOUT::Errno
+				CZTop::HasFFIDelegate.raise_zmq_err
+			end
+			return nil
+		end
+		return Event.new(self, @event_ptr)
+	end
+
+
+	### Modify the underlying poller's event mask with the events +socket+ is
+	### interested in.
+	def update_poller_for( socket )
+		event_mask = self.mask_for( socket )
+
+		ptr = self.ptr_for_socket( socket )
+		rc = CZTop::Poller::ZMQ.poller_modify( @poller_ptr, ptr, event_mask )
+		CZTop::HasFFIDelegate.raise_zmq_err if rc == -1
+	end
+
+
+	### Return the ZMQ bitmask for the events the specified +socket+ is registered
+	### for.
+	def mask_for( socket )
+		return self.sockets[ socket ][ :events ].inject( 0 ) do |mask, evt|
+			mask | VALID_EVENTS[ evt ]
+		end
+	end
+
+
+	### Return the low-level handle for +socket+. Raises an ArgumentError if argument is
+	### not a CZTop::Socket or a CZTop::Actor.
+	def ptr_for_socket( socket )
+		unless socket.is_a?( CZTop::Socket ) || socket.is_a?( CZTop::Actor )
+			raise ArgumentError, "expected a CZTop::Socket or a CZTop::Actor, got %p" % [ socket ]
+		end
+		return CZMQ::FFI::Zsock.resolve( socket )
+	end
+
+end # class CZTop::Reactor
+

data/lib/cztop/reactor/event.rb

@@ -0,0 +1,68 @@
+# -*- ruby -*-
+#encoding: utf-8
+
+require 'cztop'
+require 'cztop/poller'
+require 'cztop/reactor' unless defined?( CZTop::Reactor )
+
+
+
+# Represents an event returned by {CZTop::Poller#wait}.
+class CZTop::Reactor::Event
+
+	# Poll events in bitwise order
+	POLL_EVENTS = [
+		:read,
+		:write,
+		:err
+	]
+
+
+	### Create a new event from the specified +reactor+ and +event_ptr+.
+	def initialize( reactor, event_ptr )
+		@reactor = reactor
+		@poller_event = CZTop::Poller::ZMQ::PollerEvent.new( event_ptr )
+	end
+
+
+	##
+	# The CZTop::Reactor that generated this event
+	attr_reader :reactor
+
+
+	### Get the Socket or Actor the event corresponds to.
+	def socket
+		return @socket ||= self.reactor.socket_for_ptr( @poller_event[:socket] )
+	end
+
+
+	### Returns +true+ if the event indicates the socket is readable.
+	def readable?
+		return @poller_event.readable?
+	end
+
+
+	### Returns +true+ if the event indicates the socket is writable.
+	def writable?
+		return @poller_event.writable?
+	end
+
+
+	### Return the poll events this event represents.
+	def poll_events
+		return POLL_EVENTS.select.with_index {|ev,i| @poller_event[:events][i].nonzero? }
+	end
+
+
+	### Return a human-readable string representation of the event suitable for
+	### debugging.
+	def inspect
+		return "#<%p:%#016x %p {%s}>" % [
+			self.class,
+			self.object_id * 2,
+			self.socket,
+			self.poll_events.map( &:to_s ).join( '/' )
+		]
+	end
+
+end # class CZTop::Reactor::Event

data/spec/cztop/reactor/event_spec.rb

@@ -0,0 +1,41 @@
+#!/usr/bin/env rspec -cfd
+
+require_relative '../../spec_helper'
+
+require 'cztop/reactor/event'
+
+
+describe CZTop::Reactor::Event do
+
+	DummyPollerEvent = Struct.new( :DummyPollerEvent, :readable?, :writable?, :socket, :events )
+
+
+	before( :each ) do
+		allow( CZTop::Poller::ZMQ::PollerEvent ).to receive( :new ).and_return( poller_event )
+	end
+
+
+	let( :reactor ) { CZTop::Reactor.new }
+	let( :poller_event ) do
+		DummyPollerEvent.new( false, false, nil, 0 )
+	end
+
+
+	it "looks up the socket via the reactor it was created with" do
+		poller_event.socket = 0xDEADBEEF
+		event = described_class.new( reactor, 0xFADECAFE )
+
+		expect( reactor ).to receive( :socket_for_ptr ).with( 0xDEADBEEF ).and_return( :the_socket )
+		expect( event.socket ).to eq( :the_socket )
+	end
+
+
+	it "knows the poll event(s) that caused it" do
+		poller_event.events = CZTop::Poller::ZMQ::POLLIN|CZTop::Poller::ZMQ::POLLERR
+		event = described_class.new( reactor, 0xFADECAFE )
+
+		expect( event.poll_events ).to contain_exactly( :read, :err )
+	end
+
+end
+

data/spec/cztop/reactor_spec.rb

@@ -0,0 +1,183 @@
+#!/usr/bin/env rspec -cfd
+#encoding: utf-8
+
+require_relative '../spec_helper'
+
+require 'rspec'
+require 'cztop/reactor'
+
+describe CZTop::Reactor do
+
+	let( :reactor ) { described_class.new }
+
+
+	describe "socket registration" do
+
+		let( :socket ) { CZTop::Socket::REP.new }
+
+
+		it "allows a socket to be registered for reads" do
+			expect( reactor ).to_not be_registered( socket )
+			expect( reactor ).to_not have_event_enabled( socket, :read )
+			expect( reactor ).to_not have_event_enabled( socket, :write )
+
+			reactor.register( socket, :read ) {}
+
+			expect( reactor ).to be_registered( socket )
+			expect( reactor ).to have_event_enabled( socket, :read )
+			expect( reactor ).to_not have_event_enabled( socket, :write )
+		end
+
+
+		it "allows a socket to be registered for reads and writes" do
+			expect( reactor ).to_not be_registered( socket )
+			expect( reactor ).to_not have_event_enabled( socket, :read )
+			expect( reactor ).to_not have_event_enabled( socket, :write )
+
+			reactor.register( socket, :read, :write ) {}
+
+			expect( reactor ).to be_registered( socket )
+			expect( reactor ).to have_event_enabled( socket, :read )
+			expect( reactor ).to have_event_enabled( socket, :write )
+		end
+
+
+		it "errors if no block is given when registering a socket" do
+			expect {
+				reactor.register( socket, :read )
+			}.to raise_error( LocalJumpError, /no handler/i )
+		end
+
+
+		it "allows a registered socket to be unregistered" do
+			reactor.register( socket, :read, :write ) {}
+			reactor.unregister( socket )
+
+			expect( reactor ).to_not be_registered( socket )
+		end
+
+
+		it "doesn't error when unregistering an unregistered socket" do
+			expect {
+				reactor.unregister( socket )
+			}.to_not raise_error
+		end
+
+
+		it "allows a socket to have one or more events enabled for it after registration" do
+			reactor.register( socket ) {}
+			expect( reactor ).to_not have_event_enabled( socket, :read )
+			expect( reactor ).to_not have_event_enabled( socket, :write )
+
+			reactor.enable_events( socket, :read )
+			expect( reactor ).to have_event_enabled( socket, :read )
+			expect( reactor ).to_not have_event_enabled( socket, :write )
+
+			reactor.enable_events( socket, :write )
+			expect( reactor ).to have_event_enabled( socket, :read )
+			expect( reactor ).to have_event_enabled( socket, :write )
+		end
+
+
+		it "allows a socket to have one or more events disabled for it after registration" do
+			reactor.register( socket, :read, :write ) {}
+			expect( reactor ).to have_event_enabled( socket, :read )
+			expect( reactor ).to have_event_enabled( socket, :write )
+
+			reactor.disable_events( socket, :read )
+			expect( reactor ).to_not have_event_enabled( socket, :read )
+			expect( reactor ).to have_event_enabled( socket, :write )
+
+			reactor.disable_events( socket, :write )
+			expect( reactor ).to_not have_event_enabled( socket, :read )
+			expect( reactor ).to_not have_event_enabled( socket, :write )
+		end
+
+
+		it "can unregister all of its registered sockets" do
+			reactor.register( socket ) {}
+			reactor.register( CZTop::Socket::SUB.new ) {}
+			reactor.register( CZTop::Socket::REQ.new ) {}
+
+			reactor.clear
+
+			expect( reactor.sockets ).to be_empty
+		end
+
+	end
+
+
+	describe "timer registration" do
+
+		it "allows a callback to be called after a certain amount of time" do
+			handle = reactor.add_oneshot_timer( 5 ) {}
+			expect( reactor.timers ).to include( handle )
+		end
+
+
+		it "allows a callback to be called periodically on an interval" do
+			handle = reactor.add_periodic_timer( 5 ) {}
+			expect( reactor.timers ).to include( handle )
+		end
+
+
+		it "allows a timer to be cancelled" do
+			handle = reactor.add_periodic_timer( 5 ) {}
+			reactor.remove_timer( handle )
+			expect( reactor.timers ).to_not include( handle )
+		end
+
+	end
+
+
+	describe "monitors" do
+
+		it "can create and register a monitor for a socket" do
+			socket = CZTop::Socket::REP.new
+			begin
+				monitor = reactor.register_monitor( socket ) {}
+				expect( monitor ).to be_a( CZTop::Monitor )
+				expect( reactor ).to be_registered( monitor.actor )
+			ensure
+				monitor.terminate if monitor
+			end
+		end
+
+	end
+
+
+	describe "polling loop" do
+
+		it "processes events until it has no more sockets" do
+			reader = CZTop::Socket::PAIR.new( '@inproc://polling-test' )
+			writer = CZTop::Socket::PAIR.new( '>inproc://polling-test' )
+
+			data = nil
+
+			reactor.register( writer, :write ) do |ev|
+				ev.socket << "stuff"
+				reactor.unregister( writer )
+			end
+			reactor.register( reader, :read ) do |ev|
+				msg = ev.socket.receive
+				data = msg.frames.first.content
+				reactor.stop_polling
+			end
+
+			thr = Thread.new do
+				Thread.current.abort_on_exception = true
+				reactor.start_polling
+			end
+
+			thr.join( 2 )
+			thr.kill if thr.alive?
+
+			expect( data ).to eq( "stuff" )
+		end
+
+
+	end
+
+
+end
+

data/spec/spec_helper.rb

@@ -0,0 +1,23 @@
+# -*- ruby -*-
+#encoding: utf-8
+
+require 'simplecov' if ENV['COVERAGE']
+
+require 'rspec'
+
+require 'loggability/spechelpers'
+
+
+### Mock with RSpec
+RSpec.configure do |config|
+	config.run_all_when_everything_filtered = true
+	config.filter_run :focus
+	config.order = 'random'
+	config.mock_with( :rspec ) do |mock|
+		mock.syntax = :expect
+	end
+
+	config.include( Loggability::SpecHelpers )
+end
+
+

metadata

@@ -0,0 +1,250 @@
+--- !ruby/object:Gem::Specification
+name: cztop-reactor
+version: !ruby/object:Gem::Version
+  version: 0.1.0.pre20170316155217
+platform: ruby
+authors:
+- Michael Granger
+autorequire: 
+bindir: bin
+cert_chain:
+- |
+  -----BEGIN CERTIFICATE-----
+  MIIEbDCCAtSgAwIBAgIBATANBgkqhkiG9w0BAQsFADA+MQwwCgYDVQQDDANnZWQx
+  GTAXBgoJkiaJk/IsZAEZFglGYWVyaWVNVUQxEzARBgoJkiaJk/IsZAEZFgNvcmcw
+  HhcNMTYwODIwMTgxNzQyWhcNMTcwODIwMTgxNzQyWjA+MQwwCgYDVQQDDANnZWQx
+  GTAXBgoJkiaJk/IsZAEZFglGYWVyaWVNVUQxEzARBgoJkiaJk/IsZAEZFgNvcmcw
+  ggGiMA0GCSqGSIb3DQEBAQUAA4IBjwAwggGKAoIBgQC/JWGRHO+USzR97vXjkFgt
+  83qeNf2KHkcvrRTSnR64i6um/ziin0I0oX23H7VYrDJC9A/uoUa5nGRJS5Zw/+wW
+  ENcvWVZS4iUzi4dsYJGY6yEOsXh2CcF46+QevV8iE+UmbkU75V7Dy1JCaUOyizEt
+  TH5UHsOtUU7k9TYARt/TgYZKuaoAMZZd5qyVqhF1vV+7/Qzmp89NGflXf2xYP26a
+  4MAX2qqKX/FKXqmFO+AGsbwYTEds1mksBF3fGsFgsQWxftG8GfZQ9+Cyu2+l1eOw
+  cZ+lPcg834G9DrqW2zhqUoLr1MTly4pqxYGb7XoDhoR7dd1kFE2a067+DzWC/ADt
+  +QkcqWUm5oh1fN0eqr7NsZlVJDulFgdiiYPQiIN7UNsii4Wc9aZqBoGcYfBeQNPZ
+  soo/6za/bWajOKUmDhpqvaiRv9EDpVLzuj53uDoukMMwxCMfgb04+ckQ0t2G7wqc
+  /D+K9JW9DDs3Yjgv9k4h7YMhW5gftosd+NkNC/+Y2CkCAwEAAaN1MHMwCQYDVR0T
+  BAIwADALBgNVHQ8EBAMCBLAwHQYDVR0OBBYEFHKN/nkRusdqCJEuq3lgB3fJvyTg
+  MBwGA1UdEQQVMBOBEWdlZEBGYWVyaWVNVUQub3JnMBwGA1UdEgQVMBOBEWdlZEBG
+  YWVyaWVNVUQub3JnMA0GCSqGSIb3DQEBCwUAA4IBgQAPJzKiT0zBU7kpqe0aS2qb
+  FI0PJ4y5I8buU4IZGUD5NEt/N7pZNfOyBxkrZkXhS44Fp+xwBH5ebLbq/WY78Bqd
+  db0z6ZgW4LMYMpWFfbXsRbd9TU2f52L8oMAhxOvF7Of5qJMVWuFQ8FPagk2iHrdH
+  inYLQagqAF6goWTXgAJCdPd6SNeeSNqA6vlY7CV1Jh5kfNJJ6xu/CVij1GzCLu/5
+  DMOr26DBv+qLJRRC/2h34uX71q5QgeOyxvMg+7V3u/Q06DXyQ2VgeeqiwDFFpEH0
+  PFkdPO6ZqbTRcLfNH7mFgCBJjsfSjJrn0sPBlYyOXgCoByfZnZyrIMH/UY+lgQqS
+  6Von1VDsfQm0eJh5zYZD64ZF86phSR7mUX3mXItwH04HrZwkWpvgd871DZVR3i1n
+  w8aNA5re5+Rt/Vvjxj5AcEnZnZiz5x959NaddQocX32Z1unHw44pzRNUur1GInfW
+  p4vpx2kUSFSAGjtCbDGTNV2AH8w9OU4xEmNz8c5lyoA=
+  -----END CERTIFICATE-----
+date: 2017-03-16 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: loggability
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.14'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.14'
+- !ruby/object:Gem::Dependency
+  name: cztop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.11'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.11'
+- !ruby/object:Gem::Dependency
+  name: timers
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.1'
+- !ruby/object:Gem::Dependency
+  name: hoe-mercurial
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.4'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.4'
+- !ruby/object:Gem::Dependency
+  name: hoe-deveiate
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+- !ruby/object:Gem::Dependency
+  name: hoe-highline
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.13'
+- !ruby/object:Gem::Dependency
+  name: rdoc-generator-fivefish
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.3'
+- !ruby/object:Gem::Dependency
+  name: rdoc
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+- !ruby/object:Gem::Dependency
+  name: hoe
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.15'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.15'
+description: |-
+  This is an implementation of the Reactor pattern described in [Pattern-Oriented
+  Software Architecture (Volume 2)][POSA2]. It allows an asynchronous application
+  to be described as one or more "reactions" to events, in this case either I/O
+  conditions on a ZMQ socket or a timer expiring.
+
+  A simple example:
+
+      # Start a SERVER socket, and print out any messages sent to it
+      reactor = CZTop::Reactor.new
+      socket = CZTop::Socket::SERVER.new
+      socket.bind( 'tcp://0.0.0.0:8' )
+      reactor.register( socket, :read ) do |event|
+        if event.readable?
+          message = event.socket.receive
+          puts "Read: %p" % [ message.to_a ]
+        end
+      end
+      reactor.start_polling
+email:
+- ged@FaerieMUD.org
+executables: []
+extensions: []
+extra_rdoc_files:
+- History.md
+- LICENSE.txt
+- Manifest.txt
+- README.md
+files:
+- ".document"
+- ".rdoc_options"
+- ".simplecov"
+- ChangeLog
+- History.md
+- LICENSE.txt
+- Manifest.txt
+- README.md
+- Rakefile
+- lib/cztop/reactor.rb
+- lib/cztop/reactor/event.rb
+- spec/cztop/reactor/event_spec.rb
+- spec/cztop/reactor_spec.rb
+- spec/spec_helper.rb
+homepage: http://deveiate.org/projects/cztop-reactor
+licenses:
+- ISC
+metadata: {}
+post_install_message: 
+rdoc_options:
+- "--main"
+- README.md
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.2.4
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">"
+    - !ruby/object:Gem::Version
+      version: 1.3.1
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.6.8
+signing_key: 
+specification_version: 4
+summary: This is an implementation of the Reactor pattern described in [Pattern-Oriented
+  Software Architecture (Volume 2)][POSA2]
+test_files: []