openhab-scripting 4.7.1 → 4.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e5e39f0dd326751e6c61fcf44a85f6a9033c72fc6196f899d59305f7e77ff2cf
-  data.tar.gz: 207a22d5633a711bdc333d1fb94befa787a6fa63a1b1050607c9f7665e1149f7
+  metadata.gz: 59b0441f0cce1fb707bfb5d74d051135ce37c63128359cfa98cdae2573b920d2
+  data.tar.gz: 0101f396a6bce5e6d52f3191973fb6db2f3cb3be93f00229b4cc5297f04488bf
 SHA512:
-  metadata.gz: cc744a57eaad8487ffcc3bb31584bfd484ee27de0948c07a1ac47be5953e5ee2fda4a1a0713f49fda4c289ffb298908d32d69741ce83ee3c526f0bec7c5ae173
-  data.tar.gz: 42a1fa4aa68bc0d81399f02de37761598005bed645b105f85f14af6d3419578938a3cbd33cd8a6c03b0fed46031c25730dca23074063d98ba76cc0eea43ccf24
+  metadata.gz: ac154dd9d98ca0305c30770286554cb0b4bc863f1af95e7e03a32090aac7cc8f13633a42d2bcd8da7bc8b585f377a4db74d8a4ef668675ac0704fed9627f9973
+  data.tar.gz: bc241f0713e34124057fb124658dd13b4437bbe455bbf975c616aefd6a05b49a8d224039e23175dd7c1c350a17fa782eec2c8d22748e56f24cf8e618774396a2

data/lib/openhab/dsl/items/items.rb

@@ -22,6 +22,7 @@ require_relative 'rollershutter_item'
 require_relative 'string_item'
 
 require_relative 'ensure'
+require_relative 'timed_command'
 
 module OpenHAB
   module DSL
@@ -65,9 +66,9 @@ module OpenHAB
 
             logger.trace("Defining #{klass}##{command} for #{value}")
             klass.class_eval <<~RUBY, __FILE__, __LINE__ + 1
-              def #{command}       # def on
-                command(#{value})  #   command(ON)
-              end                  # end
+              def #{command}(for: nil, on_expire: nil, &block)                                          # def on(for: nil, on_expire: nil, &block )
+                command(#{value}, for: binding.local_variable_get(:for), on_expire: on_expire, &block)  #   command(ON, for: nil, expire: nil, &block)
+              end                                                                                       # end
             RUBY
 
             logger.trace("Defining GroupItem::GroupMembers##{command} for #{value}")

data/lib/openhab/dsl/items/timed_command.rb

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+
+require 'openhab/dsl/timers'
+require 'openhab/dsl/rules/triggers/trigger'
+require 'java'
+
+require_relative 'generic_item'
+
+module OpenHAB
+  module DSL
+    module Items
+      # Module enables timed commands e.g. Switch.on for: 3.minutes
+      module TimedCommand
+        # Stores information about timed commands
+        TimedCommandDetails = Struct.new(:item, :command, :was, :duration, :on_expire, :timer, :expired, :cancel_rule,
+                                         :rule_uid, keyword_init: true) do
+          def expired?
+            expired
+          end
+
+          def canceled?
+            !expired?
+          end
+        end
+
+        @timed_commands = {}
+
+        class << self
+          attr_reader :timed_commands
+        end
+
+        # Extensions for {Items::GenericItem} to implement timed commands
+        module GenericItem
+          #
+          #  Sends command to an item for specified duration, then on timer expiration sends
+          #  the expiration command to the item
+          #
+          # @param [Types::Type] command to send to object
+          # @param [Duration] for duration for item to be in command state
+          # @param [Types::Type] on_expire Command to send when duration expires
+          #
+          #
+          # rubocop: disable Metrics/MethodLength
+          # The mutex makes this over 10 lines, but there is usable way to break thsi method up
+          def command(command, for: nil, on_expire: nil, &block)
+            duration = binding.local_variable_get(:for)
+            return super(command) unless duration
+
+            # Timer needs access to rule to disable, rule needs access to timer to cancel.
+            # Using a mutux to ensure neither fires before the other is constructed
+            semaphore = Mutex.new
+
+            semaphore.synchronize do
+              timed_command_details = TimedCommand.timed_commands[self]
+              if timed_command_details.nil?
+                create_timed_command(command: command, duration: duration,
+                                     semaphore: semaphore, on_expire: on_expire, &block)
+              else
+                logger.trace "Outstanding Timed Command #{timed_command_details} encountered - rescheduling"
+                timed_command_details.duration = duration # Capture updated duration
+                timed_command_details.timer.reschedule duration
+              end
+            end
+
+            self
+          end
+          # rubocop: enable Metrics/MethodLength
+          alias << command
+
+          private
+
+          # Creates a new timed command and places it in the TimedCommand hash
+          # rubocop: disable Metrics/AbcSize
+          # rubocop: disable Metrics/MethodLength
+          # There is no feasible way to break this method into smaller components
+          def create_timed_command(command:, duration:, semaphore:, on_expire:, &block)
+            on_expire ||= default_on_expire(command)
+            timed_command_details = TimedCommandDetails.new(item: self, command: command, was: state,
+                                                            on_expire: on_expire, duration: duration)
+
+            # Send specified command after capturing current state
+            command(command)
+
+            timed_command_details.timer = timed_command_timer(timed_command_details, semaphore, &block)
+            timed_command_details.cancel_rule = TimedCommandCancelRule.new(timed_command_details, semaphore,
+                                                                           &block)
+            timed_command_details.rule_uid = OpenHAB::DSL::Rules.automation_manager
+                                                                .addRule(timed_command_details.cancel_rule).getUID
+            logger.trace "Created Timed Command #{timed_command_details}"
+            TimedCommand.timed_commands[self] = timed_command_details
+          end
+          # rubocop: enable Metrics/AbcSize
+          # rubocop: enable Metrics/MethodLength
+
+          # Creates the timer to handle changing the item state when timer expires or invoking user supplied block
+          # @param [TimedCommandDetailes] timed_command_details details about the timed command
+          # @param [Mutex] semaphore Semaphore to lock on to prevent race condition between rule and timer
+          # @return [Timer] Timer
+          # rubocop: disable Metrics/MethodLength
+          # There is no feasible way to break this method into smaller components
+          def timed_command_timer(timed_command_details, semaphore, &block)
+            after(timed_command_details.duration, id: self) do
+              semaphore.synchronize do
+                logger.trace "Timed command expired - #{timed_command_details}"
+                cancel_timed_command_rule(timed_command_details)
+                timed_command_details.expired = true
+                if block
+                  logger.trace "Invoking block #{block} after timed command for #{id} expired"
+                  yield(timed_command_details)
+                else
+                  command(timed_command_details.on_expire)
+                end
+
+                TimedCommand.timed_commands.delete(timed_command_details.item)
+              end
+            end
+          end
+          # rubocop: enable Metrics/MethodLength
+
+          # Cancels timed command rule
+          # @param [TimedCommandDetailed] timed_command details about the timed command
+          def cancel_timed_command_rule(timed_command_details)
+            logger.trace "Removing rule: #{timed_command_details.rule_uid}"
+            OpenHAB::DSL::Rules.registry.remove(timed_command_details.rule_uid)
+          end
+
+          #
+          # The default expire for ON/OFF is their inverse
+          #
+          def default_on_expire(command)
+            case format_type_pre(command)
+            when ON then OFF
+            when OFF then ON
+            else state
+            end
+          end
+
+          #
+          # Rule to cancel timed commands
+          #
+          class TimedCommandCancelRule < Java::OrgOpenhabCoreAutomationModuleScriptRulesupportSharedSimple::SimpleRule
+            include OpenHAB::Log
+            def initialize(timed_command_details, semaphore, &block)
+              super()
+              @semaphore = semaphore
+              @timed_command_details = timed_command_details
+              @block = block
+              set_name("Cancels implicit timer for #{timed_command_details.item.id}")
+              set_triggers([OpenHAB::DSL::Rules::Triggers::Trigger.trigger(
+                type: OpenHAB::DSL::Rules::Triggers::Trigger::ITEM_STATE_UPDATE,
+                config: { 'itemName' => timed_command_details.item.name }
+              )])
+            end
+
+            #
+            # Execute the rule
+            #
+            # @param [Map] mod map provided by OpenHAB rules engine
+            # @param [Map] inputs map provided by OpenHAB rules engine containing event and other information
+            #
+            #
+            # rubocop: disable Metrics/MethodLength
+            # rubocop: disable Metrics/AbcSize
+            # There is no feasible way to break this method into smaller components
+            def execute(_mod = nil, inputs = nil)
+              @semaphore.synchronize do
+                logger.trace "Canceling implicit timer #{@timed_command_details.timer} for "\
+                             "#{@timed_command_details.item.id}  because received event #{inputs}"
+                @timed_command_details.timer.cancel
+                # rubocop: disable Style/GlobalVars
+                # Disabled due to OpenHAB design
+                $scriptExtension.get('ruleRegistry').remove(@timed_command_details.rule_uid)
+                # rubocop: enable Style/GlobalVars
+                TimedCommand.timed_commands.delete(@timed_command_details.item)
+                if @block
+                  logger.trace 'Executing user supplied block on timed command cancelation'
+                  @block&.call(@timed_command_details)
+                end
+              end
+            end
+            # rubocop: enable Metrics/MethodLength
+            # rubocop: enable Metrics/AbcSize
+          end
+        end
+      end
+      GenericItem.prepend(TimedCommand::GenericItem)
+    end
+  end
+end

data/lib/openhab/dsl/rules/automation_rule.rb

@@ -68,8 +68,7 @@ module OpenHAB
         # Cleanup any resources associated with automation rule
         #
         def cleanup
-          logger.trace "Cancelling #{@trigger_delays.length} Trigger Delays(s) for rule '#{name}'"
-          @trigger_delays.each_value { |trigger_delay| trigger_delay.timer&.cancel }
+          # No cleanup is necessary right now, trigger delays are tracked and cancelled by timers library
         end
 
         private
@@ -230,9 +229,9 @@ module OpenHAB
             logger.trace("Item changed to #{state} for #{trigger_delay}, rescheduling timer.")
             trigger_delay.timer.reschedule(ZonedDateTime.now.plus(trigger_delay.duration))
           else
-            logger.trace("Item changed to #{state} for #{trigger_delay}, cancelling timer.")
+            logger.trace("Item changed to #{state} for #{trigger_delay}, canceling timer.")
             trigger_delay.timer.cancel
-            # Reprocess trigger delay after cancelling to track new state (if guards matched, etc)
+            # Reprocess trigger delay after canceling to track new state (if guards matched, etc)
             process_trigger_delay(trigger_delay, mod, inputs)
           end
         end

data/lib/openhab/dsl/rules/rule.rb

@@ -15,8 +15,13 @@ module OpenHAB
     module Rules
       @script_rules = []
 
+      # rubocop: disable Style/GlobalVars
+      @automation_manager = $scriptExtension.get('automationManager')
+      @registry = $scriptExtension.get('ruleRegistry')
+      # rubocop: enable Style/GlobalVars
+
       class << self
-        attr_reader :script_rules
+        attr_reader :script_rules, :automation_manager, :registry
       end
 
       #
@@ -134,9 +139,7 @@ module OpenHAB
       #
       #
       def add_rule(rule)
-        # rubocop: disable Style/GlobalVars
-        $scriptExtension.get('automationManager').addRule(rule)
-        # rubocop: enable Style/GlobalVars
+        Rules.automation_manager.addRule(rule)
       end
     end
   end

data/lib/openhab/dsl/timers/manager.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require 'openhab/log/logger'
+require_relative 'reentrant_timer'
+
+module OpenHAB
+  module DSL
+    #
+    # Provides access to and ruby wrappers around OpenHAB timers
+    #
+    module Timers
+      #
+      # Manages data structures that track timers
+      #
+      class TimerManager
+        include OpenHAB::Log
+
+        attr_reader :timer_ids
+
+        def initialize
+          # Track timer IDs
+          @timer_ids = Hash.new { |hash, key| hash[key] = Set.new }
+
+          # Reentrant timer lookups
+          @reentrant_timers = {}
+
+          # Tracks active timers
+          @timers = Set.new
+        end
+
+        #
+        # Adds the current timer to the set of rule timers if being tracked
+        #
+        # rubocop: disable Metrics/AbcSize
+        # It does not make sense to break this up into seperate components
+        def add(timer)
+          logger.trace("Adding #{timer} to timers")
+          @timers << timer
+
+          if timer.respond_to? :id
+            logger.trace("Adding #{timer} with id #{timer.id.inspect} timer ids")
+            @timer_ids[timer.id] << timer
+          end
+
+          return unless timer.respond_to? :reentrant_id
+
+          logger.trace("Adding reeentrant #{timer} with reentrant id #{timer.reentrant_id} timer ids")
+          @reentrant_timers[timer.reentrant_id] = timer
+        end
+        # rubocop: enable Metrics/AbcSize
+
+        # Fetches the reentrant timer that matches the supplied id and block if it exists
+        #
+        # @param [Object] Object to associate with timer
+        # @param [Block] block to execute, block is passed a Timer object
+        #
+        # @return [RentrantTimer] Timer object if it exists, nil otherwise
+        #
+        def reentrant_timer(id:, &block)
+          reentrant_key = ReentrantTimer.reentrant_id(id: id, &block)
+          logger.trace("Checking for existing reentrant timer for #{reentrant_key}")
+          @reentrant_timers[reentrant_key]
+        end
+
+        #
+        # Delete the current timer to the set of rule timers if being tracked
+        #
+        def delete(timer)
+          logger.trace("Removing #{timer} from timers")
+          @timers.delete(timer)
+          @timer_ids[timer.id].delete(timer) if (timer.respond_to? :id) && (@timer_ids.key? timer.id)
+          @reentrant_timers.delete(timer.reentrant_id) if timer.respond_to? :reentrant_id
+        end
+
+        #
+        # Cancels all active timers
+        #
+        def cancel_all
+          logger.trace("Canceling #{@timers.length} timers")
+          @timers.each(&:cancel)
+          @timer_ids.clear
+          @reentrant_timers.clear
+          @timers.clear
+        end
+      end
+    end
+  end
+end

data/lib/openhab/dsl/timers/reentrant_timer.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require 'openhab/log/logger'
+require_relative 'timer'
+
+module OpenHAB
+  module DSL
+    #
+    # Provides access to and ruby wrappers around OpenHAB timers
+    #
+    module Timers
+      # A reentrant timer is a timer that is automatically rescheduled
+      # when the block it refers to is encountered again
+      #
+      # @author Brian O'Connell
+      # @since 2.0.0
+      class ReentrantTimer < Timer
+        include OpenHAB::Log
+
+        attr_reader :id, :reentrant_id
+
+        #
+        # Create a new Timer Object
+        #
+        # @param [Duration] duration Duration until timer should fire
+        # @param [Block] block Block to execute when timer fires
+        #
+        def initialize(duration:, id:, &block)
+          raise 'Reentrant timers do not work in dynamically generated code' unless block.source_location
+
+          @id = id
+          @reentrant_id = self.class.reentrant_id(id: id, &block)
+          super(duration: duration, &block)
+          logger.trace("Created Reentrant Timer #{self} with reentrant Key #{@reentrant_id}")
+        end
+
+        def self.reentrant_id(id:, &block)
+          [id, block.source_location].flatten
+        end
+      end
+    end
+  end
+end

data/lib/openhab/dsl/timers/timer.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require 'java'
+require 'delegate'
+require 'forwardable'
+require 'openhab/log/logger'
+
+module OpenHAB
+  module DSL
+    #
+    # Provides access to and ruby wrappers around OpenHAB timers
+    #
+    module Timers
+      include OpenHAB::Log
+      java_import org.openhab.core.model.script.actions.ScriptExecution
+      java_import java.time.ZonedDateTime
+
+      # Ruby wrapper for OpenHAB Timer
+      # This class implements delegator to delegate methods to the OpenHAB timer
+      #
+      # @author Brian O'Connell
+      # @since 2.0.0
+      class Timer < SimpleDelegator
+        include OpenHAB::Log
+        extend Forwardable
+
+        def_delegator :@timer, :is_active, :active?
+        def_delegator :@timer, :is_running, :running?
+        def_delegator :@timer, :has_terminated, :terminated?
+
+        #
+        # Create a new Timer Object
+        #
+        # @param [Duration] duration Duration until timer should fire
+        # @param [Block] block Block to execute when timer fires
+        #
+        def initialize(duration:, &block)
+          @duration = duration
+
+          # A semaphore is used to prevent a race condition in which calling the block from the timer thread
+          # occurs before the @timer variable can be set resulting in @timer being nil
+          semaphore = Mutex.new
+
+          semaphore.synchronize do
+            @timer = ScriptExecution.createTimer(
+              ZonedDateTime.now.plus(@duration), timer_block(semaphore, &block)
+            )
+            @rule_timers = Thread.current[:rule_timers]
+            super(@timer)
+            Timers.timer_manager.add(self)
+          end
+        end
+
+        #
+        # Reschedule timer
+        #
+        # @param [Duration] duration
+        #
+        # @return [Timer] Rescheduled timer instances
+        #
+        def reschedule(duration = nil)
+          duration ||= @duration
+          Timers.timer_manager.add(self)
+          @timer.reschedule(ZonedDateTime.now.plus(duration))
+        end
+
+        # Cancel timer
+        #
+        # @return [Boolean] True if cancel was successful, false otherwise
+        #
+        def cancel
+          Timers.timer_manager.delete(self)
+          @timer.cancel
+        end
+
+        private
+
+        #
+        # Constructs a block to execute timer within
+        #
+        # @param [Semaphore] Semaphore to obtain before executing
+        #
+        # @return [Proc] Block for timer to execute
+        #
+        def timer_block(semaphore)
+          proc {
+            semaphore.synchronize do
+              Timers.timer_manager.delete(self)
+              yield(self)
+            end
+          }
+        end
+      end
+    end
+  end
+end

data/lib/openhab/dsl/timers.rb

@@ -1,9 +1,8 @@
 # frozen_string_literal: true
 
-require 'java'
-require 'delegate'
-require 'forwardable'
-require 'openhab/log/logger'
+require_relative 'timers/timer'
+require_relative 'timers/manager'
+require_relative 'timers/reentrant_timer'
 
 module OpenHAB
   module DSL
@@ -12,109 +11,58 @@ module OpenHAB
     #
     module Timers
       include OpenHAB::Log
-      java_import org.openhab.core.model.script.actions.ScriptExecution
-      java_import java.time.ZonedDateTime
 
-      # Tracks active timers
-      @timers = Set.new
-      class << self
-        attr_accessor :timers
-      end
-
-      # Ruby wrapper for OpenHAB Timer
-      # This class implements delegator to delegate methods to the OpenHAB timer
-      #
-      # @author Brian O'Connell
-      # @since 2.0.0
-      class Timer < SimpleDelegator
-        include OpenHAB::Log
-        extend Forwardable
-
-        def_delegator :@timer, :is_active, :active?
-        def_delegator :@timer, :is_running, :running?
-        def_delegator :@timer, :has_terminated, :terminated?
-
-        #
-        # Create a new Timer Object
-        #
-        # @param [Duration] duration Duration until timer should fire
-        # @param [Block] block Block to execute when timer fires
-        #
-        def initialize(duration:, &block)
-          @duration = duration
-
-          # A semaphore is used to prevent a race condition in which calling the block from the timer thread
-          # occurs before the @timer variable can be set resulting in @timer being nil
-          semaphore = Mutex.new
-
-          semaphore.synchronize do
-            @timer = ScriptExecution.createTimer(
-              ZonedDateTime.now.plus(@duration), timer_block(semaphore, &block)
-            )
-            super(@timer)
-            Timers.timers << self
-          end
-        end
-
-        #
-        # Reschedule timer
-        #
-        # @param [Duration] duration
-        #
-        # @return [Timer] Rescheduled timer instances
-        #
-        def reschedule(duration = nil)
-          duration ||= @duration
-          Timers.timers << self
-          @timer.reschedule(ZonedDateTime.now.plus(duration))
-        end
-
-        # Cancel timer
-        #
-        # @return [Boolean] True if cancel was successful, false otherwise
-        #
-        def cancel
-          Timers.timers.delete(self)
-          @timer.cancel
-        end
+      # Manages timers
+      @timer_manager = TimerManager.new
 
-        private
-
-        #
-        # Constructs a block to execute timer within
-        #
-        # @param [Semaphore] Semaphore to obtain before executing
-        #
-        # @return [Proc] Block for timer to execute
-        #
-        def timer_block(semaphore)
-          proc {
-            semaphore.synchronize do
-              Timers.timers.delete(self)
-              yield(self)
-            end
-          }
-        end
+      class << self
+        attr_reader :timer_manager
       end
 
       #
       # Execute the supplied block after the specified duration
       #
       # @param [Duration] duration after which to execute the block
+      # @param [Object] id to associate with timer
       # @param [Block] block to execute, block is passed a Timer object
       #
       # @return [Timer] Timer object
       #
-      def after(duration, &block)
+      def after(duration, id: nil, &block)
+        return Timers.reentrant_timer(duration: duration, id: id, &block) if id
+
         Timer.new(duration: duration, &block)
       end
 
+      #
+      # Provdes access to the hash for mapping timer ids to the set of active timers associated with that id
+      # @return [Hash] hash of user specified ids to sets of times
+      def timers
+        Timers.timer_manager.timer_ids
+      end
+
       #
       # Cancels all active timers
       #
       def self.cancel_all
-        logger.trace("Cancelling #{@timers.length} timers")
-        @timers.each(&:cancel)
+        @timer_manager.cancel_all
+      end
+
+      # Create or reschedule a reentrant time
+      #
+      # @param [Duration] duration after which to execute the block
+      # @param [Object] id to associate with timer
+      # @param [Block] block to execute, block is passed a Timer object
+      # @return [ReentrantTimer] Timer object
+      def self.reentrant_timer(duration:, id:, &block)
+        timer = @timer_manager.reentrant_timer(id: id, &block)
+        if timer
+          logger.trace("Reentrant timer found - #{timer}")
+          timer.reschedule
+        else
+          logger.trace('No reentrant timer found, creating new timer')
+          ReentrantTimer.new(duration: duration, id: id, &block)
+        end
       end
     end
   end

data/lib/openhab/version.rb

@@ -5,5 +5,5 @@
 #
 module OpenHAB
   # @return [String] Version of OpenHAB helper libraries
-  VERSION = '4.7.1'
+  VERSION = '4.8.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: openhab-scripting
 version: !ruby/object:Gem::Version
-  version: 4.7.1
+  version: 4.8.0
 platform: ruby
 authors:
 - Brian O'Connell
@@ -77,6 +77,7 @@ files:
 - lib/openhab/dsl/items/rollershutter_item.rb
 - lib/openhab/dsl/items/string_item.rb
 - lib/openhab/dsl/items/switch_item.rb
+- lib/openhab/dsl/items/timed_command.rb
 - lib/openhab/dsl/lazy_array.rb
 - lib/openhab/dsl/monkey_patch/actions/actions.rb
 - lib/openhab/dsl/monkey_patch/actions/script_thing_actions.rb
@@ -106,6 +107,9 @@ files:
 - lib/openhab/dsl/things.rb
 - lib/openhab/dsl/time_of_day.rb
 - lib/openhab/dsl/timers.rb
+- lib/openhab/dsl/timers/manager.rb
+- lib/openhab/dsl/timers/reentrant_timer.rb
+- lib/openhab/dsl/timers/timer.rb
 - lib/openhab/dsl/types/comparable_type.rb
 - lib/openhab/dsl/types/date_time_type.rb
 - lib/openhab/dsl/types/decimal_type.rb