brown 2.2.0 → 2.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 831f8702bad84d8fe35c098f0a624632ab06f835
-  data.tar.gz: 55684d48c7e8233a7cd6d68621f77116e2b05f49
+  metadata.gz: 80d8b8839069b1aef10dc6a78f8d300b7f0d0191
+  data.tar.gz: 76552fb92abda3c6e4362fb8bcc12f2a602c8e14
 SHA512:
-  metadata.gz: f879eb251cb5b9e511d4331a2b5e84c1c8590a80a846bf7c1d7ff813f50bf359be28a7421ffa5b718e5190d6a2fa59e25139c47f9399529d203bd8427a238096
-  data.tar.gz: cbf37ca7b491d245d85e389d74ad91187d6824ec86503010b054b5eb9e0a7c5ab00950eaaa871df283a487f684843b59bdae48f18d8f0d6d854c3cb216d4ac52
+  metadata.gz: 71edb2cda3ba54528d608bc5032e008d501bfd79de97cbb168516ca407c1086ae46fc2a9d21645d6ba5346a03e1534a32261a913338f1326f238a481b1d33b50
+  data.tar.gz: e1bc450d4ab6eeb14aae29184676481598c25a43b949b596f28e279a462d6f0924da00cdd26897432fec6cf81692b977fb6af5eb5970994098e82aaa2cc1410b

data/README.md

@@ -90,6 +90,172 @@ You can pass arguments to the agent method call, by giving them to
 `worker.call`.
 
 
+## Agent-wide common variables
+
+There is some state you will want to keep across the entire agent.  For
+this, Brown provides the concept of "memos".  These are persistent objects,
+which you access via a class or instance method.  To declare them, you
+simply do:
+
+    class MemoUser < Brown::Agent
+      memo(:foo) { Foo.new }
+    end
+
+The way this works is that the memo defines a method (both class and
+instance) which, the first time you run it, runs the provided block to
+create the memo object.  Thereafter, that cached object is provided to the
+caller of the memo method.
+
+Because of Brown's multi-threaded nature, memos come with a built-in mutex
+to prevent concurrent usage.  That means that every time you want to access
+the memo, you must do so inside a block:
+
+    class MemoUser < Brown::Agent
+      memo(:foo) { Foo.new }
+
+      every(10) do
+        foo do |f|
+          f.frob
+        end
+      end
+    end
+
+The crucial thing to note here is that you *only have the memo lock inside
+the block*.  If you were to capture the memo object into a variable outside
+the block, and then use it (read *or* write) outside the block, Really Bad
+Things can happen.  So **don't do that**.
+
+When you have multiple memos, it is entirely possible that you can end up
+deadlocking your agent by acquiring the locks for various memos in different
+orders.  Those dining philosophers are always getting themselves in a
+muddle.  To prevent this problem, it is highly recommended that you always
+acquire the locks for your memos in the order they are written in the class
+definition:
+
+    class MemoUser < Brown::Agent
+      memo(:foo) { Foo.new }
+      memo(:bar) { Bar.new }
+
+      every(5) do
+        # Acquiring a single lock is OK
+        foo do |f|
+          f.brob
+        end
+      end
+
+      every(6) do
+        # Acquiring a single lock, even if it is later in the
+        # list, is fine
+        bar do |b|
+          b.baznicate(b)
+        end
+      end
+
+      every(7) do
+        # This is the right order to acquire nested locks
+        foo do |f|
+          bar do |b|
+            f.frob(b)
+          end
+        end
+      end
+
+      every(7) do
+        # This is THE WRONG WAY AROUND.  DO NOT DO THIS!
+        # YOU WILL GET DEADLOCKS!
+        bar do |b|
+          foo do |f|
+            b.baznicate(f)
+          end
+        end
+      end
+    end
+
+Another "gotcha" in the world of memos is that the memoised object itself is
+persistent.  When you get the lock, and the memo object comes in via the
+argument to your block, that is *a reference* to the memo object.  That
+means that reassigning that variable to a new object won't change the value
+of the memo object:
+
+    class MemoUser < Brown::Agent
+      memo(:now) { Time.now }
+
+      every(5) do
+        now do |t|
+          puts t
+        end
+      end
+
+      every(60) do
+        now do |t|
+          t = Time.now
+        end
+      end
+    end
+
+The above code will *always* print the time as at the first time that `now`
+was called, even though every minute we *think* we're resetting the memo
+value to a new `Time`.
+
+The "hack" around this is to use a single-value array to "contain" the
+object that we actually want to periodically replace:
+
+    class MutableMemoUser < Brown::Agent
+      memo(:now) { [Time.now] }
+
+      every(5) do
+        now do |t|
+          puts t[0]
+        end
+      end
+
+      every(60) do
+        now to |t|
+          t[0] = Time.now
+        end
+      end
+    end
+
+This example code will print the same time for a minute, before changing to
+a new minute.
+
+
+### Thread-safe memos
+
+There are some classes which are themselves thread-safe -- usually because
+the class author has gone to some trouble to provide zer own, more
+fine-grained, locking on the data within the object.  If you are *quite
+sure* you have such a thread-safe object to memoise, you can use
+{Brown::Agent::ClassMethods.safe_memo} for that purpose:
+
+    class SafeMemoUser < Brown::Agent
+      safe_memo(:foo) { ThreadSafeFoo.new }
+    end
+
+The benefit of this form of memos is that you don't have to access them in a
+block:
+
+    class SafeMemoUser < Brown::Agent
+      safe_memo(:foo) { ThreadSafeFoo.new }
+
+      every(10) do
+        foo.frob
+      end
+    end
+
+Like regular memos, you cannot reassign a thread-safe memo to another
+object:
+
+    class SafeMemoUser < Brown::Agent
+      safe_memo(:foo) { ThreadSafeFoo.new }
+
+      every(10) do
+        # This will explode with a NameError
+        foo = ThreadSafeFoo.new
+      end
+    end
+
+
 ## AMQP publishing / consumption
 
 Since message-based communication is a common pattern amongst cooperating

data/bin/brown

@@ -23,10 +23,10 @@ Brown::Agent.logger = Logger.new($stderr)
 Brown::Agent.logger.level = Logger.const_get(ENVied.BROWN_LOG_LEVEL.upcase.to_sym)
 Brown::Agent.logger.formatter = proc { |s,dt,n,msg| "#{$$}-#{Thread.current.object_id} [#{s[0]}] #{msg}\n" }
 
-agents = ThreadGroup.new
+agents = []
 
 def stop_agents(agents)
-	agents.list.each do |th|
+	agents.each do |th|
 		th[:agent_class] && th[:agent_class].stop
 	end
 end
@@ -53,39 +53,45 @@ Brown::Agent.logger.info { "Brown starting up..." }
 
 agent_classes.each do |klass|
 	th = Thread.new(klass) do |klass|
+		Thread.current[:agent_class] = klass
 		klass.run
-		Thread[:agent_class] = klass
 	end
 
-	agents.add(th)
+	agents << th
 
 	Brown::Agent.logger.info { "Started agent #{klass}" }
 end
 
 loop do
-	sleep 1
+	if agents.empty?
+		break
+	end
 
-	agents.list.each do |th|
+	agents.each do |th|
 		unless th.alive?
 			begin
-				th.join
+				th.join(0.5)
 			rescue Exception => ex
 				Brown::Agent.logger.fatal { "Agent #{th[:agent_class]} crashed: #{ex.message} (#{ex.class})" }
 				Brown::Agent.logger.info { ex.backtrace.map { |l| "  #{l}" }.join("\n") }
-			else
-				Brown::Agent.logger.warn "Agent #{th[:agent_class]} terminated itself"
-			end
-			klass = th[:agent_class]
-			th[:agent_class] = nil
 
-			Brown::Agent.logger.info { "Re-starting #{klass} agent" }
+				Brown::Agent.logger.info { "Re-starting #{klass} agent" }
 
-			th = Thread.new(klass) do |klass|
-				klass.run
-				Thread[:agent_class] = klass
+				new_th = Thread.new(klass) do |klass|
+					Thread.current[:agent_class] = klass
+					klass.run
+				end
+
+				agents << new_th
+			else
+				Brown::Agent.logger.warn "Agent #{th[:agent_class]} exited cleanly; not restarting"
 			end
 
-			agents.add(th)
+			klass = th[:agent_class]
+			th[:agent_class] = nil
+			agents.delete(th)
 		end
 	end
 end
+
+Brown::Agent.logger.info { "Brown exiting" }

data/lib/brown/agent.rb

@@ -351,6 +351,8 @@ class Brown::Agent
 			(@thread_group.list rescue []).each do |th|
 				th.join
 			end
+
+			@runner_thread.raise(Brown::StopSignal.new("Clean stop"))
 		end
 
 		# Set the logger that this agent will use to report problems.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: brown
 version: !ruby/object:Gem::Version
-  version: 2.2.0
+  version: 2.2.1
 platform: ruby
 authors:
 - Matt Palmer
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-06-13 00:00:00.000000000 Z
+date: 2015-06-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bunny