brown 2.2.2 → 2.2.2.25.g85ddf08

data/lib/brown/agent/class_methods.rb

@@ -0,0 +1,166 @@
+require 'logger'
+require 'securerandom'
+
+module Brown::Agent::ClassMethods
+	# The available stimuli.
+	#
+	# @return [Array<Hash<Symbol, Object>>]
+	#
+	attr_reader :stimuli
+
+	# The available memos.
+	#
+	# @return [Array<Hash<Symbol, Object>>]
+	#
+	attr_reader :memos
+
+	# Define a generic stimulus for this agent.
+	#
+	# This is a fairly low-level method, designed to provide a means for
+	# defining stimuli for which there isn't a higher-level, more-specific
+	# stimulus definition approach.
+	#
+	# When the agent is started (see {.run}), the block you provide will be
+	# executed in a dedicated thread.  Every time the block finishes, it will be
+	# run again.  Your block should do whatever it needs to do to detect when a
+	# stimuli is available (preferably by blocking somehow, rather than polling,
+	# because polling sucks).  When your code detects that a stimulus has been
+	# received, it should run `worker.call`, passing in any arguments that are
+	# required to process the stimulus.  That will then spawn a new thread and
+	# call the specified `method_name` on the agent object, passing in the
+	# arguments that were passed to `worker.call`.
+	#
+	# @see .every
+	#
+	# @param method_name [Symbol] the name of the method to call when the
+	#   stimulus is triggered.
+	#
+	# @yieldparam worker [Proc] call this when you want a stimulus
+	#   processed, passing in anything that the stimulus processing method
+	#   (as specified by `method_name`) needs to do its job.
+	#
+	def stimulate(method_name, stimulus_name, &blk)
+		@stimuli ||= []
+
+		@stimuli << {
+			name: stimulus_name,
+			method_name:  method_name,
+			stimuli_proc: blk,
+		}
+	end
+
+	# Define a "memo" for this agent.
+	#
+	# A "memo" is an object which is common across all instances of a
+	# particular agent, and which is (usually) local to that agent.  The
+	# intended purpose is for anything that is needed for processing
+	# stimuli, but which you don't want to recreate for every stimuli.
+	# Examples of this sort of thing include connection pools (database,
+	# HTTP connections, etc), config files, and caches.  Basically,
+	# anything that has a non-trivial setup time, or which you *want* to
+	# share across all stimuli processing, should go in a memo.
+	#
+	# Because we do everything in threads, and because dealing with locking by
+	# hand is a nightmare, access to memos is protected by a mutex.  This means
+	# that any time you want to do something with a memo, you call its name and
+	# pass a block to do whatever you want to do with the value, like this:
+	#
+	#     config { |cfg| puts "foo is #{cfg[:foo]}" }
+	#
+	# Now, you can, if you want, "leak" this object out of the mutex, with
+	# various sorts of assignment.  DO NOT SUCCUMB TO THIS TEMPTATION.  If
+	# you do this, you will risk all sorts of concurrency bugs, where two
+	# threads try to read and/or manipulate the object at the same time
+	# and all hell breaks loose.
+	#
+	# Note that there is intentionally no way to reassign a memo object.
+	# This doesn't mean that memo objects are "read-only", however.  The
+	# state of the object can be mutated by calling any method on the
+	# object that modifies it.  If you want more read-only(ish) memos, you
+	# probably want to call `#freeze` on your object when you create it
+	# (although all the usual caveats about the many limitations of `#freeze`
+	# still apply).
+	#
+	# @param name [Symbol] the name of the memo, and hence the name of the
+	#   method that should be called to retrieve the memo's value.
+	#
+	# @return void
+	#
+	def memo(name, &generator)
+		define_method(name) do |&blk|
+			raise RuntimeError, "Memo values are only available inside a block" unless blk
+
+			@memo_mutexes_mutex.synchronize do
+				@memo_mutexes[name] ||= Mutex.new
+			end
+
+			@memo_mutexes[name].synchronize do
+				@memo_values[name] ||= instance_eval(&generator)
+				blk.call(@memo_values[name])
+			end
+		end
+	end
+
+	# Execute a block of code periodically.
+	#
+	# This pretty much does what it says on the tin.  Every
+	# `n` seconds (where `n` can be a float) the given block
+	# of code is executed.
+	#
+	# Don't expect too much precision in the interval; we just sleep
+	# between triggers, so there might be a bit of an extra delay between
+	# invocations.
+	#
+	# @param n [Numeric] The amount of time which should elapse between
+	#   invocations of the block.
+	#
+	# @param desc [#to_s] a descriptive name to use for the trigger in
+	#   metrics and the suchlike.  If you define two stimuli with the same
+	#   periodicity, you *must* give them different descriptions.
+	#
+	# @yield every `n` seconds.
+	#
+	def every(n, desc = "every_#{n}", &blk)
+		method_name = desc.to_sym
+		define_method(method_name, &blk)
+
+		stimulate(method_name, desc) { |worker| Kernel.sleep n; worker.call }
+	end
+
+	# Keep a block of code running, calling it again whenever it exits.
+	#
+	# @param desc [#to_s] a descriptive name to use for the trigger.
+	#   Each `respawn` block must have its own description.
+	#
+	# @yield every time the code block finishes.
+	#
+	def respawn(desc, &blk)
+		mutex   = Mutex.new
+		cv      = ConditionVariable.new
+		running = false
+
+		method_name = desc.to_sym
+		define_method(method_name) do
+			mutex.synchronize do
+				begin
+					instance_eval(&blk)
+				ensure
+					running = false
+					cv.signal
+				end
+			end
+		end
+
+		stimulate(method_name, desc) do |worker|
+			mutex.synchronize do
+				while running
+					cv.wait(mutex)
+				end
+				running = true
+				worker.call
+			end
+		end
+	end
+end
+
+Brown::Agent.extend(Brown::Agent::ClassMethods)

data/lib/brown/agent/stimulus.rb

@@ -1,3 +1,5 @@
+require "service_skeleton/background_worker"
+
 # A single stimulus group in a Brown Agent.
 #
 # This is all the behind-the-scenes plumbing that's required to make the
@@ -6,11 +8,13 @@
 # terribly, terribly wrong somewhere.
 #
 class Brown::Agent::Stimulus
-	# The name of the method to call when the stimulus is triggered.
+	include ServiceSkeleton::BackgroundWorker
+
+	# The (bound) method to call when the stimulus is triggered.
 	#
 	# @return [String]
 	#
-	attr_reader :method_name
+	attr_reader :method
 
 	# The chunk of code to call over and over again to listen for the stimulus.
 	#
@@ -18,35 +22,40 @@ class Brown::Agent::Stimulus
 	#
 	attr_reader :stimuli_proc
 
-	# The class to instantiate to process a stimulus.
-	#
-	# @return [Class]
-	#
-	attr_reader :agent_class
-
 	# Create a new stimulus.
 	#
-	# @param method_name [String] The method to call on an instance of
-	#   `agent_class` to process a single stimulus event.
-	#
-	# @param stimuli_proc [Proc] What to call over and over again to listen
-	#   for new stimulus events.
+	# @param method [String] The (bound) method to call to process a single
+	#   stimulus event.
 	#
-	# @param agent_class [Class] The class to instantiate when processing
-	#   stimulus events.
+	# @param stimuli_proc [Proc] What to call over and over again to collect
+	#   the next stimulus event.
 	#
 	# @param logger [Logger] Where to log things to for this stimulus.
 	#   If left as the default, no logging will be done.
 	#
-	def initialize(method_name:, stimuli_proc:, agent_class:, logger: Logger.new("/dev/null"))
-		@method_name  = method_name
+	# @param metrics [Brown::Agent::Stimulus::Metrics] Somewhere to record
+	#   all the important numbers about the stimulus.
+	#
+	def initialize(method:, stimuli_proc:, logger: Logger.new("/dev/null"), metrics:)
+		puts caller if method.nil?
+		@method       = method
 		@stimuli_proc = stimuli_proc
-		@agent_class  = agent_class
-		@thread_group = ThreadGroup.new
+		@threads      = ThreadGroup.new
 		@logger       = logger
+		@metrics      = metrics
+
+		super
 	end
 
-	# Fire off the stimulus listener.
+	def start
+		@running = true
+
+		while @running
+			run
+		end
+	end
+
+	# Run the stimulus listener.
 	#
 	# @param once [Symbol, NilClass] Ordinarily, when the stimulus is run, it
 	#   just keeps going forever (or until stopped, at least).  If you just
@@ -55,89 +64,87 @@ class Brown::Agent::Stimulus
 	#
 	def run(once = nil)
 		if once == :once
-			stimuli_proc.call(->(*args) { process(*args) })
+			@metrics.last_trigger.set({}, Time.now.to_f)
+			@metrics.processing_ruler.measure do
+				stimuli_proc.call(->(*args) { process(*args) })
+			end
 		else
-			@runner_thread = Thread.current
-			begin
-				while @runner_thread
-					begin
-						stimuli_proc.call(method(:spawn_worker))
-					rescue Brown::StopSignal, Brown::FinishSignal
-						raise
-					rescue Exception => ex
-						log_failure("Stimuli listener", ex)
+			@running = true
+			logger.debug(logloc) { "Running stimulus listener for stimulus proc at #{@method.source_location.join(":")}" }
+			Thread.handle_interrupt(Exception => :never) do
+				begin
+					while @running
+						begin
+							logger.debug(logloc) { "Calling stimulus_proc" }
+							Thread.handle_interrupt(Exception => :immediate) do
+								@metrics.last_trigger.set({}, Time.now.to_f)
+								@metrics.processing_ruler.measure do
+									stimuli_proc.call(->(*args) { spawn_worker(*args) })
+								end
+							end
+						rescue StandardError => ex
+							log_exception(ex) { "Stimuli listener proc raised exception" }
+							sleep 1
+						end
 					end
+				rescue ServiceSkeleton::BackgroundWorker.const_get(:TerminateBackgroundThread) => ex
+					@threads.list.each { |th| th.raise(ex.class) }
+					raise unless Thread.current == @bg_worker_thread
+				rescue StandardError => ex
+					log_exception(ex) { "Mysterious exception while running stimulus listener for #{method.name}" }
 				end
-			rescue Brown::StopSignal
-				stop
-			rescue Brown::FinishSignal
-				finish
-			rescue Exception => ex
-				log_failure("Stimuli runner", ex)
 			end
 		end
 	end
 
-	# Signal the stimulus to immediately shut down everything.
-	#
-	# This will cause all stimulus processing threads to be terminated
-	# immediately.  You probably want to use {#finish} instead, normally.
+	# Gracefully stop all stimuli workers.
 	#
-	def stop
-		@thread_group.list.each do |th|
-			th.raise Brown::StopSignal.new("stimulus thread_group")
-		end
+	def shutdown
+		logger.info(progname) { "shutting down" }
+		@running = false
 
-		finish
-	end
+		logger.debug(progname) { "waiting for #{@threads.list.length} stimuli worker(s) to finish" }
 
-	# Stop the stimulus listener, and wait gracefull for all currently
-	# in-progress stimuli processing to finish before returning.
-	#
-	def finish
-		if @runner_thread and @runner_thread != Thread.current
-			@runner_thread.raise(Brown::StopSignal.new("stimulus loop"))
+		until @threads.list.empty? do
+			@threads.list.first.join
 		end
-		@runner_thread = nil
 
-		@thread_group.list.each { |th| th.join }
+		logger.debug(progname) { "terminating stimulus listener" }
+		super
+
+		logger.info(progname) { "shutdown complete." }
 	end
 
 	private
 
+	attr_reader :logger
+
+	def progname
+		@progname ||= "StimulusWorker->#{method.name rescue nil}"
+	end
+
 	# Process a single stimulus event.
 	#
 	def process(*args)
-		instance = agent_class.new
-
-		if instance.method(method_name).arity == 0
-			instance.__send__(method_name)
+		logger.debug(progname) { "Processing stimulus.  Arguments: #{args.inspect}" }
+		if method.arity == 0
+			method.call
 		else
-			instance.__send__(method_name, *args)
+			method.call(*args)
 		end
 	end
 
 	# Fire off a new thread to process a single stimulus event.
 	#
 	def spawn_worker(*args)
-		@thread_group.add(
-			Thread.new(args) do |args|
-				begin
-					process(*args)
-				rescue Brown::StopSignal, Brown::FinishSignal
-					# We're OK with this; the thread will now
-					# quietly die.
-				rescue Exception => ex
-					log_failure("Stimulus worker", ex)
-				end
-			end
-		)
-	end
+		@threads.add(Thread.new(args) do |args|
+			logger.debug(progname) { "Spawned new worker" }
 
-	# Standard log formatting for caught exceptions.
-	#
-	def log_failure(what, ex)
-		@logger.error { "#{what} failed: #{ex.message} (#{ex.class})" }
-		@logger.info  { ex.backtrace.map { |l| "    #{l}" }.join("\n") }
+			begin
+				process(*args)
+			rescue StandardError => ex
+				log_exception(ex) { "Stimulus worker raised exception" }
+			end
+		end)
 	end
 end

data/lib/brown/agent/stimulus/metrics.rb

@@ -0,0 +1,17 @@
+require "frankenstein/request"
+
+# A bundle of metrics intended for a single arbitrary stimulus.
+#
+#
+class Brown::Agent::Stimulus::Metrics
+	# The Frankenstein::Request instance for the stimulus processing.
+	attr_reader :processing_ruler
+
+	# When the stimulus last fired.
+	attr_reader :last_trigger
+
+	def initialize(prefix, registry:)
+		@processing_ruler = Frankenstein::Request.new(prefix, outgoing: false, registry: registry)
+		@last_trigger     = registry.gauge(:"#{prefix}_last_trigger_timestamp_seconds", "When this stimulus was most recently triggered")
+	end
+end

data/lib/brown/rspec.rb

@@ -1,10 +1,21 @@
 require 'brown/test'
 
-RSpec.configure do |c|
-	c.after(:each) do
-		ObjectSpace.each_object(Class).each do |klass|
-			if klass != Brown::Agent and klass.ancestors.include?(Brown::Agent)
-				klass.reset_memos
+module Brown::SpecHelpers
+	def self.included(mod)
+		mod.let(:agent_env) { { "AMQP_URL" => "amqp://spec.example.invalid" } }
+		mod.let(:agent) { described_class.new(agent_env) }
+
+		if mod.described_class.respond_to?(:amqp_publishers)
+			(mod.described_class.amqp_publishers || []).each do |publisher|
+				mod.let(:"#{publisher[:name]}_publisher") { instance_double(Brown::Agent::AMQPPublisher, publisher[:name]) }
+			end
+		end
+
+		mod.before(:each) do
+			if described_class.respond_to?(:amqp_publishers)
+				(described_class.amqp_publishers || []).each do |publisher|
+					allow(agent).to receive(publisher[:name]).and_return(send(:"#{publisher[:name]}_publisher"))
+				end
 			end
 		end
 	end

data/lib/brown/test.rb

@@ -8,16 +8,6 @@ require 'brown/agent/amqp_message_mock'
 #     require 'brown/test'
 #
 module Brown::TestHelpers
-	#:nodoc:
-	def self.included(base)
-		base.class_eval do
-			%i{memo amqp_publisher amqp_listener}.each do |m|
-				alias_method "#{m}_without_test".to_sym, m
-				alias_method m, "#{m}_with_test".to_sym
-			end
-		end
-	end
-
 	# Is there not an arbitrary stimulus with the specified name registered
 	# on this agent?
 	#
@@ -44,8 +34,8 @@ module Brown::TestHelpers
 	# Test-specific decorator to replace the "real" memo container object
 	# with a test-enabled alternative.
 	#
-	def memo_with_test(name, safe=false, &generator)
-		memo_without_test(name, safe, &generator)
+	def memo(name, safe=false, &generator)
+		super
 
 		# Throw out the real memo, replace with our own testing-enabled variant
 		@memos[name] = Brown::Agent::Memo.new(generator, safe, true)
@@ -100,12 +90,15 @@ module Brown::TestHelpers
 	#
 	# Test-specific decorator to record the existence of a publisher.
 	#
-	def amqp_publisher_with_test(name, *args)
+	def amqp_publisher(name, *args)
 		@amqp_publishers ||= {}
 
 		@amqp_publishers[name] = true
 
-		amqp_publisher_without_test(name, *args)
+		publisher =
+		self.define_singleton_method
+
+		super
 	end
 
 	# Is there a publisher with the specified name registered on this agent?
@@ -122,7 +115,7 @@ module Brown::TestHelpers
 	#
 	# Test-specific decorator to record the details of a listener.
 	#
-	def amqp_listener_with_test(exchange_name, *args, &blk)
+	def amqp_listener(exchange_name, *args, &blk)
 		@amqp_listeners ||= {}
 
 		if exchange_name.is_a? Array
@@ -133,7 +126,7 @@ module Brown::TestHelpers
 			@amqp_listeners[exchange_name.to_s] = blk
 		end
 
-		amqp_listener_without_test(exchange_name, *args, &blk)
+		super
 	end
 
 	# Is there a listener on the specified exchange name registered on this agent?
@@ -163,23 +156,18 @@ module Brown::TestHelpers
 	#   that isn't being listened on.
 	#
 	def amqp_receive(exchange_name, payload, **opts)
-		unless amqp_listener?(exchange_name)
-			raise ArgumentError,
-			      "Unknown exchange: #{exchange_name}"
-		end
-
 		msg = Brown::Agent::AMQPMessageMock.new(opts.merge(payload: payload))
 
-		self.new.tap do |p|
-			uuid = SecureRandom.uuid
-			p.singleton_class.__send__(:define_method, uuid, &@amqp_listeners[exchange_name])
-			p.__send__(uuid, msg)
+		(self.class.amqp_listeners || []).each do |listener|
+			if listener[:exchange_list].include?(exchange_name.to_s)
+				m = SecureRandom.uuid
+				define_singleton_method(m.to_sym, &listener[:callback])
+				__send__(m.to_sym, msg)
+			end
 		end
 
 		msg.acked?
 	end
 end
 
-class << Brown::Agent
-	include Brown::TestHelpers
-end
+Brown::Agent.prepend(Brown::TestHelpers)