rsmp 0.8.0 → 0.8.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9614e6db6381449fa893901766de8239b7bc025c4454724709dc32b75551b5f3
-  data.tar.gz: fce1a7fb067481f5ca199301bbd91953d0dd8d13f07e66ad365a5ffa24e58966
+  metadata.gz: d6e0bddb9443fd704586251f92785f5ec4d703431d587047f8a2e835fcb48b9f
+  data.tar.gz: 81b56b1687ad356177b6277d58f6db4ed4d3f8fa8e59aa0fc626a90fcc03bb86
 SHA512:
-  metadata.gz: b942ee93f8185051dadac06576087ca8b27b11f8e3c653cb9638a72464941dd72c82c566ede50a46d2bffeb16c809345ef78b3edef7174a74d8ea75e963fa8f1
-  data.tar.gz: 0052cb6afefed493e4ac4e2d48f4c587afe3f377ddabd2492fbeb3c223ff78e39b23ac7b01cd5e564abc3474a5f8f0b35b6edc93c24c453876597c478365ac2a
+  metadata.gz: d8ba189a5602f9ec1bc7f09e821231c2f5135dd163da82ffae48b9a9f62ac79ec8d4beb114e6112d41902fc1ca06ccff2a208863d00f05e51c9a83cafb68e33c
+  data.tar.gz: 4fd8b04217edb49b3c1b929ac3d585c60194207cdb8380be7693ee00b448a28fce90cc6e55621b6cee601d773f80c6780c0d7a3a31ee8606f62f23cfce0718f8

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    rsmp (0.8.0)
+    rsmp (0.8.4)
       async (~> 1.29.1)
       async-io (~> 1.32.1)
       colorize (~> 0.8.1)
@@ -70,8 +70,8 @@ GEM
       cucumber-cucumber-expressions (~> 12.1, >= 12.1.1)
       cucumber-messages (~> 15.0, >= 15.0.0)
     diff-lcs (1.4.4)
-    ecma-re-validator (0.3.0)
-      regexp_parser (~> 2.0)
+    ecma-re-validator (0.4.0)
+      regexp_parser (~> 2.2)
     ffi (1.15.3)
     fiber-local (1.0.0)
     hana (1.3.7)

data/config/tlc.yaml

@@ -20,17 +20,18 @@ signal_plans:
     dynamic_bands:
       1: 0
       2: 5
-    states:
-      A1: '11NBBB'
-      A2: '1NBBBB'
-      B1: 'BBB11N'
-      B2: 'BBB1NB'
-  2:
     states:
       A1: '111NBB'
       A2: '11NBBB'
       B1: 'BBB11N'
       B2: 'BBB1NB'
+  2:
+    states:
+      A1: 'NNNNBB'
+      A2: 'NNNNBN'
+      B1: 'BBNNNN'
+      B2: 'BNNNNN'
+startup_sequence: 'efg'
 intervals:
   timer: 0.1
   watchdog: 0.1
@@ -48,3 +49,4 @@ log:
   level: false
   debug: true
   json: true
+live_output: tmp/tlc.state

data/documentation/classes_and_modules.md

@@ -19,9 +19,6 @@ Handle logging.
 ### Wait
 Handles waiting for an async condition and block.
 
-### SiteProxyWait
-Handles waiting for different types of messages and responses from a remote site.
-
 ### Components
 Component handling.
 
@@ -38,7 +35,7 @@ A Site has one or more SupervisorProxies (connections to supervisor).
 
 A site has one of more components.
 
-### Supervisor 
+### Supervisor
 A Supervisor represents an RSMP supervisor, typically a central supervisor system. An RSMP supervisor can handle connections one or more sites.
 
 A Supervisor has one or more SiteProxies (connections to sites).

data/documentation/collecting_message.md

@@ -0,0 +1,196 @@
+# Collection
+You often need to collect messages or responses. The collector classes are used to collect message asyncronously. Other tasks continue until the collection completes, time outs or is cancelled.
+
+A collector can collect ingoing and/or outgoing messages. 
+
+An object that includes the Notifier module (or implements the same functionality) must be provided when you construct a Collected. The collector will attach itself to this notifier when it starts collecting, to receive messages. The SiteProxy and SupervisorProxy classes both include the Notifier module, and can therefore be used as message sources.
+
+Messages that match the relevant criteria are stored by the collector.
+
+When the collection is done, the collector detaches from the notifier, and returns the status.
+
+
+## Collector
+Class uses for collecting messages filtered by message type, direction and/or component id. A block can be used for custom filtering.
+
+You can choose to collect a specific number of message and/or for a specific duration.
+
+A collector has a status, which is `:ready` initialialy. When you start collecting, it changes to `:collecting`. It will be `:ok` once collection completes successfully, or `:cancel` if it was cancelled to to some error or by a filter block.
+
+### Initialization
+When you create a collector, you specify the messages types you want to collect.
+You can also specify ingoing and/or outgoing direction and the RSMP component.
+
+```ruby
+collector = MessageCollector.new notifier, num: 10, ingoing: true, outgoing: true
+```
+
+num: The number of messages to collect. If not provided, a timeout must be set instead.
+timeout: The number of seconds to collect
+ingoing: Whether to collect ingoing messages. Defaults to true
+outgoing: Whether to collect outgoing messages. Defaults to true
+component: An RSMP component id.
+
+### Collecting
+Use collect() to start collecting and wait for completion or timeout. The status will be returned. 
+
+```ruby
+result = collector.collect # => :ok, :timeout or :cancelled
+collector.messages # => collected messages
+```
+
+If you want start collection, but not wait for the result, use `start()`. You can then later use `wait()` if you want:
+
+```ruby
+result = collector.start # => nil
+# do other stuff
+result = collector.wait
+```
+
+### Custom filtering
+You can use a block to do extra filtering. The block will be callled for each messages that fulfils the  correct message type, direction and component id.
+
+The block must return nil or a list of symbols to indicate whether the message should be kept, and whether collection should be cancelled.
+
+```ruby
+result = collector.collect do |message|
+	:keep, :cancel 		# example of how to keep the message and cancel collection
+end
+```
+
+`:keep` keeps (collect) this message
+`:cancel` cancel collection
+
+Note that you cannot use `return` in a block. You can either simply provide the values as the last expresssion in the block, or use next().
+
+Exceptions in the block will cause the collector to abort. If the collect! or wait! variants are used, the exception is propagated to the caller.
+
+### Bang version
+The method collect!() will raise exceptions in case of errors, and will return the collect message directly.
+
+```ruby
+message = collector.collect # => collected message.
+```
+
+Similar, `wait!()` will raise an exception in case of timeouts or errors:
+
+```ruby
+message = collector.wait! # => collected message.
+```
+
+
+### Schema Errors and Disconnects
+The collector can optionally cancel collection in special cases, controlled by the `:cancel` option provided when contructing the collector.
+
+```ruby
+options = {
+	cancel: {
+		disconnect: true,
+		schema_error: true
+	}
+}
+result = collector.collect options
+```
+
+disconnect: If the proxy which provides messages experience a disconnect, the collector will cancel collection.
+
+schema_error: If the proxy receives a message with a schema error, the collector will cancel collection, if the the invalid message has the correct message type.
+
+### NotAck
+A typical scenaria is that you send a command or status request, and want to collect the response. But if the original message is rejected by the site, you will received a NotAck instead of a reply. The collector classes can handle this, as long as you provide the message id of the original request in the `m_id` key of teh options when you construct the collector.
+
+If a NotAck is received with a matching `oMId` (original message id), the collection is cancelled.
+
+## StatusCollector
+Waits for a set of status criteria to be met.
+
+Note that a single RSMP status message can contain multiple status items. Unlike MessageCollector, a StatusCollector therefore operates on items, rather than messages, and you can't specify a number of messages to collect.
+
+
+### Criteria
+You construct a StatusCollector with set of criteria, specifying the status codes, names, and optionally values that must be met.
+
+### Collecting
+When you start collection, it will complete once all criteria are all fulfilled, the timeout is reached or a custom filtering block aborts the collection.
+
+```ruby
+collector = StatusCollector.new(options)
+result = matcher.collect(timeout: 5)
+```
+
+### Custom filtering
+You can use a block to do extra filtering. The block will be called for each individual status item that fulfils all criteria, like status code and name, component, etc.
+
+Like with MessageCollector, the block must return a hash specifing whether to keep the message and whether to continue collection.
+
+```ruby
+matcher = StatusCollector.new(options)
+result = matcher.collect(options) do |message,item|
+	next(:keep) if good_item?(item) 		# keep item
+end
+```
+
+## Subscribing to status updates
+The method `subscribe_to_status` can be used to subscribe to one of more status messages.
+
+### Without collection
+The simple form sends an RSMP status subscription message to the site and then returns immediatly. To collect incoming status messages, you need to manually use e.g. a Collector.
+
+A hash is returned, with `:sent` containing the send subscription messages.
+
+```ruby
+options = {
+	list: [{'sCI'=>'S0001','n'=>'signalgroupstatus'}],
+}
+result = subscribe_to_status(options)
+result.keys => # [:sent]
+```
+
+Note: If you want to use this simple form and manually collect responses, it's best to start collection in an asyncronous task _before_ you subscribe, to make sure you don't miss early responses:
+
+```ruby
+task = async do
+	MessageCollector.new(options).collect(num: 5, timeout:10)  # start listening for status messages
+end
+result = subscribe_to_status(options) # subscribe
+task.wait  # wait for collection task to complete (or time out)
+```
+
+### With collection
+If you provide `:collect` options, it will be used to construct a StatusCollector for collecting the relevant status messages. When collection completes the collector is returned in the `:collector` key:
+
+```ruby
+options = {
+	list: [{'sCI'=>'S0001','n'=>'signalgroupstatus'}],
+	collect: {timeout: 5}
+}
+result = subscribe_to_status(options)
+result.keys => # [:sent, :collector]
+result[:collector].messages # => list of collected messages
+```
+
+You can pass you own collector which will give you more control of how to collect the incoming status messages:
+
+```ruby
+collector = Collector.new(options)
+options = {collect: collector}
+result = subscribe_to_status(options)
+result.keys => # [:sent, :collector]
+result[:collector].messages # => list of collected messages
+```
+
+### Processing responses
+If you pass a block, the block will be used to construct a collector. The block will be called for each matching  status item received.
+Collection will continue until the block returns :cancel, or it times.
+
+```ruby
+options = {
+	list: [{'sCI'=>'S0001','n'=>'signalgroupstatus'}]
+}
+result = subscribe_to_status(options) do |message|
+	# do something with message
+	:keep # or not
+end
+result.keys => # [:sent, :collector]
+```
+

data/lib/rsmp/collect/aggregated_status_collector.rb

@@ -0,0 +1,9 @@
+module RSMP
+  # Class for waiting for an aggregated status response
+  class AggregatedStatusCollector < Collector
+    def initialize proxy, options={}
+      required = { type: ['AggregatedStatus','MessageNotAck'], title: 'aggregated status' }
+      super proxy, options.merge(required)
+    end
+  end
+end

data/lib/rsmp/collect/collector.rb

@@ -1,12 +1,13 @@
 module RSMP
 
-  # Collects ingoing and/or outgoing messages from a notifier.
-  # Can filter by message type and wakes up the client once the desired number of messages has been collected.
+  # Collects messages from a notifier.
+  # Can filter by message type, componet and direction.
+  # Wakes up the once the desired number of messages has been collected.
   class Collector < Listener
-    attr_reader :condition, :messages, :status, :error
+    attr_reader :condition, :messages, :status, :error, :task
 
-    def initialize proxy, options={}
-      super proxy, options
+    def initialize notifier, options={}
+      super notifier, options
       @options = {
         cancel: {
           schema_error: true,
@@ -17,15 +18,27 @@ module RSMP
       @outgoing = options[:outgoing] == nil ? false : options[:outgoing]
       @condition = Async::Notification.new
       @title = options[:title] || [@options[:type]].flatten.join('/')
+      if options[:task]
+        @task = options[:task]
+      else
+         # if notifier is a Proxy, or some other object that implements task(),
+         # then try to get the task that way
+        if notifier.respond_to? 'task'
+          @task = notifier.task
+        end
+      end
       reset
     end
 
+    def use_task task
+      @task = task
+    end
+
     # Clear all query results
     def reset
       @messages = []
       @error = nil
       @status = :ready
-      @why = nil
     end
 
     # Inspect formatter that shows the message we have collected
@@ -33,6 +46,31 @@ module RSMP
       "#<#{self.class.name}:#{self.object_id}, #{inspector(:@messages)}>"
     end
 
+    # Is collection active?
+    def collecting?
+      @status == :collecting
+    end
+
+    # Is collection active?
+    def ok?
+      @status == :ok
+    end
+
+    # Has collection time out?
+    def timeout?
+      @status == :timeout
+    end
+
+    # Is collection ready to start?
+    def ready?
+      @status == :ready
+    end
+
+    # Has collection been cancelled?
+    def cancelled?
+      @status == :cancelled
+    end
+
     # Want ingoing messages?
     def ingoing?
       @ingoing == true
@@ -43,35 +81,53 @@ module RSMP
       @outgoing == true
     end
 
-    # If collection is complete, return immeditatly. Otherwise wait until
-    # the desired messages have been collected, or timeout is reached.
-    def wait task
-      wait! task
-    rescue RSMP::TimeoutError
+    # Collect message
+    # Will return once all messages have been collected, or timeout is reached
+    def collect &block
+      start &block
+      wait
       @status
+    ensure
+      @notifier.remove_listener self if @notifier
     end
 
-    # If collection is complete, return immeditatly. Otherwise wait until
-    # the desired messages have been collected.
-    # If timeout is reached, an exceptioin is raised.
-    def wait! task
-      return @status unless @status == :collecting
-      if @options[:timeout]
-        task.with_timeout(@options[:timeout]) { @condition.wait }
-      else
-        @condition.wait
+    # Collect message
+    # Returns the collected messages, or raise an exception in case of a time out.
+    def collect! &block
+      if collect(&block) == :timeout
+        raise RSMP::TimeoutError.new describe_progress
+      end
+      @messages
+    end
+
+    # If collection is not active, return status immeditatly. Otherwise wait until
+    # the desired messages have been collected, or timeout is reached.
+    def wait
+      if collecting?
+        if @options[:timeout]
+          @task.with_timeout(@options[:timeout]) { @condition.wait }
+        else
+          @condition.wait
+        end
       end
       @status
     rescue Async::TimeoutError
       @status = :timeout
-      raise RSMP::TimeoutError.new(describe_progress)
+    end
+
+    # If collection is not active, raise an error. Otherwise wait until
+    # the desired messages have been collected.
+    # If timeout is reached, an exceptioin is raised.
+    def wait!
+      wait
+      raise RSMP::TimeoutError.new(describe_progress) if timeout?
+      @messages
     end
 
     # Start collection and return immediately
     # You can later use wait() to wait for completion
-    def start options={}, &block
-      raise RuntimeError.new("Can't begin unless ready (currenty #{@status})") unless @status == :ready
-      @options.merge! options
+    def start &block
+      raise RuntimeError.new("Can't begin unless ready (currenty #{@status})") unless ready?
       @block = block
       raise ArgumentError.new("Num, timeout or block must be provided") unless @options[:num] || @options[:timeout] || @block
       reset
@@ -79,16 +135,6 @@ module RSMP
       @notifier.add_listener self if @notifier
     end
 
-    # Collect message
-    # Will return once all messages have been collected, or timeout is reached
-    def collect task, options={}, &block
-      start options, &block
-      wait task
-      @status
-    ensure
-      @notifier.remove_listener self
-    end
-
     # Build a string describing how how progress reached before timeout
     def describe_progress
       str = "#{@title.capitalize} collection "
@@ -98,17 +144,6 @@ module RSMP
       str
     end
 
-    # Collect message
-    # Returns the collected messages, or raise an exception in case of a time out.
-    def collect! task, options={}, &block
-      case collect(task, options, &block)
-      when :timeout
-        raise RSMP::TimeoutError.new @why
-      else
-        @messages
-      end
-    end
-
     # Check if we receive a NotAck related to initiating request, identified by @m_id.
     def reject_not_ack message
       return unless @options[:m_id]
@@ -124,28 +159,26 @@ module RSMP
     # Handle message. and return true when we're done collecting
     def notify message
       raise ArgumentError unless message
-      raise RuntimeError.new("can't process message when done") unless @status == :ready || @status == :collecting
-      unless reject_not_ack(message)
-        perform_match message
-      end
+      raise RuntimeError.new("can't process message when status is :#{@status}, title: #{@title}, desc: #{describe}") unless ready? || collecting?
+      perform_match message
       @status
     end
 
+    def describe
+    end
+
     # Match message against our collection criteria
     def perform_match message
-      return unless type_match?(message)
+      return false if reject_not_ack(message)
+      return false unless type_match?(message)
       if @block
         status = [@block.call(message)].flatten
+        return unless collecting?
         keep message if status.include?(:keep)
-        if status.include?(:cancel)
-          cancel('Cancelled by block')
-        else
-          complete if done?
-        end
       else
         keep message
-        complete if done?
       end
+      complete if done?
     end
 
     # Have we collected the required number of messages?
@@ -167,8 +200,8 @@ module RSMP
       @condition.signal
     end
 
-    # The proxy experienced some error.
-    # Check if this should cause us to cancel.
+    # An error occured upstream.
+    # Check if we should cancel.
     def notify_error error, options={}
       case error
       when RSMP::SchemaError
@@ -197,7 +230,7 @@ module RSMP
     end
 
     # Abort collection
-    def cancel error
+    def cancel error=nil
       @error = error
       @status = :cancelled
       do_stop

data/lib/rsmp/collect/command_query.rb

@@ -0,0 +1,16 @@
+module RSMP
+  # Match a specific command responses
+  class CommandQuery < Query
+    # Match a return value item against a query
+    def match? item
+      return nil if @want['cCI'] && @want['cCI'] != item['cCI']
+      return nil if @want['n'] && @want['n'] != item['n']
+      if @want['v'].is_a? Regexp
+        return false if @want['v'] && item['v'] !~ @want['v']
+      else
+        return false if @want['v'] && item['v'] != @want['v']
+      end
+      true
+    end
+  end
+end

data/lib/rsmp/collect/command_response_collector.rb

@@ -0,0 +1,20 @@
+module RSMP
+  # Class for waiting for specific command responses
+  class CommandResponseCollector < StateCollector
+    def initialize proxy, want, options={}
+      super proxy, want, options.merge(
+        type: ['CommandResponse','MessageNotAck'],
+        title:'command response'
+      )
+    end
+
+    def build_query want
+      CommandQuery.new want
+    end
+
+    # Get items, in our case the return values
+    def get_items message
+      message.attributes['rvs'] || []
+    end
+  end
+end

data/lib/rsmp/collect/filter.rb

@@ -0,0 +1,31 @@
+module RSMP
+
+  # Filter messages based on type, direction and component id.
+  # Used by Collectors.
+  class Filter
+    def initialize ingoing:true, outgoing:true, type:, component:nil
+      @ingoing = ingoing
+      @outgoing = outgoing
+      @type = type
+      @component = component
+    end
+
+    # Check a message against our match criteria
+    # Return true if there's a match, false if not
+    def accept? message
+      return false if message.direction == :in && @ingoing == false
+      return false if message.direction == :out && @outgoing == false
+      if @type
+        if @type.is_a? Array
+          return false unless @type.include? message.type
+        else
+          return false unless message.type == @type
+        end
+      end
+      if @component
+        return false if message.attributes['cId'] && message.attributes['cId'] != @component
+      end
+      true
+    end
+  end
+end

data/lib/rsmp/collect/listener.rb

@@ -19,13 +19,5 @@ module RSMP
 
     def notify_error error, options={}
     end
-
-    def listen &block
-      @notifier.add_listener self
-      yield
-    ensure
-      @notifier.remove_listener self
-    end
-
   end
 end

data/lib/rsmp/collect/message_matchers.rb

@@ -1,64 +0,0 @@
-module RSMP
-  # Class for waiting for specific command responses
-  class CommandResponseMatcher < Matcher
-    def initialize proxy, want, options={}
-      super proxy, want, options.merge(
-        type: ['CommandResponse','MessageNotAck'],
-        title:'command response'
-      )
-    end
-
-    def build_query want
-      CommandQuery.new want
-    end
-
-    # Get items, in our case the return values
-    def get_items message
-      message.attributes['rvs']
-    end
-  end
-
-  # Base class for waiting for status updates or responses
-  class StatusUpdateOrResponseMatcher < Matcher
-    def initialize proxy, want, options={}
-      super proxy, want, options.merge
-    end
-
-    def build_query want
-      StatusQuery.new want
-    end
-
-    # Get items, in our case status values
-    def get_items message
-      message.attributes['sS']
-    end
-  end
-
-  # Class for waiting for specific status responses
-  class StatusResponseMatcher < StatusUpdateOrResponseMatcher
-    def initialize proxy, want, options={}
-      super proxy, want, options.merge(
-        type: ['StatusResponse','MessageNotAck'],
-        title: 'status response'
-      )
-    end
-  end
-
-  # Class for waiting for specific status responses
-  class StatusUpdateMatcher < StatusUpdateOrResponseMatcher
-    def initialize proxy, want, options={}
-      super proxy, want, options.merge(
-        type: ['StatusUpdate','MessageNotAck'],
-        title:'status update'
-      )
-    end
-  end
-
-  # Class for waiting for an aggregated status response
-  class AggregatedStatusMatcher < Collector
-    def initialize proxy, options={}
-      required = { type: ['AggregatedStatus','MessageNotAck'], title: 'aggregated status' }
-      super proxy, options.merge(required)
-    end
-  end
-end