exsys 0.6 → 1.0

data/test/support/fake_hub.rb

@@ -7,8 +7,9 @@
 class FakeHub
     DEFAULT_PASSWORD = 'pass'.ljust(8)
 
-    attr_reader   :log, :opens, :locks, :line, :speed, :mode
-    attr_accessor :password, :silent, :lockable, :garbage
+    attr_reader   :log, :opens, :locks, :line, :speed, :mode, :lock_path
+    attr_accessor :password, :silent, :lockable, :garbage, :lock_error,
+                  :ident
 
     # @param state    [Integer] initial port bitmap
     # @param path     [String]  file backing the state, so that separate
@@ -18,13 +19,19 @@ class FakeHub
     # @param delay    [Float]   pause inside a write, widening the
     #                            window a concurrent process could slip
     #                            into
+    # @param ports [Integer] how many ports this hub has
+    # @param width [Integer] hex digits in its state word.  Real hubs
+    #                         answer wider than their port count: a
+    #                         16-port unit answers eight, and the ports
+    #                         it does not have read as 1.
     def initialize(password: DEFAULT_PASSWORD, state: 0x0000,
+                   ports: 16, width: 8,
                    path: nil, lock: nil, delay: 0)
         @password = password
         @state    = state
         @flash    = state
         @path     = path
-        @lock     = lock
+        @lock_path = lock
         @delay    = delay
         @log      = []
         @opens    = 0
@@ -32,6 +39,10 @@ class FakeHub
         @silent   = false     # hub answers nothing at all
         @lockable = true      # platform allows locking the line
         @garbage  = nil       # hub answers this instead, when set
+        @lock_error = nil     # raised by flock; for the propagation test
+        @ports    = ports
+        @width    = width
+        @ident    = format('CENTOS0005%02dv02', ports)  # nil = refuse ?Q
 
         # Attach to the hub the file already describes, so that a test
         # can inspect what its subprocesses did; seed it otherwise.
@@ -57,9 +68,20 @@ class FakeHub
     # Ports currently powered, as a sorted list -- the oracle the tests
     # compare against.
     def ports_on
-        1.upto(16).select {|p| state & (1 << (p-1)) != 0 }
+        1.upto(@ports).select {|p| state & (1 << (p-1)) != 0 }
     end
 
+    # The power-on state the hub would come back to.
+    def flash_ports
+        1.upto(@ports).select {|p| flash & (1 << (p-1)) != 0 }
+    end
+
+    # Bits for ports this hub does not have.  A real one reports them
+    # set, which is why a client must write back what it read.
+    def absent = ((1 << (@width * 4)) - 1) & ~real
+
+    def real = (1 << @ports) - 1
+
     # Record how the line was opened, so a test can check the library
     # asks for the device and the speed the hub actually needs.
     def opened(line, speed, mode)
@@ -67,18 +89,13 @@ class FakeHub
         @opens += 1
     end
 
-    def flock(mode)
-        raise Errno::ENOTSUP unless @lockable
+    # Called by each opened line before it locks.  The lock handle
+    # itself belongs to the line, not to the hub, so that two threads
+    # hold two of them and genuinely contend.
+    def lock_attempted
+        raise @lock_error            if @lock_error   # must NOT be swallowed
+        raise Errno::ENOTSUP         unless @lockable # platform refusal
         @locks += 1
-        return 0 if @lock.nil?
-
-        @lockfh = File.open(@lock, File::RDWR|File::CREAT, 0o600)
-        @lockfh.flock(mode)
-    end
-
-    def unlock
-        @lockfh&.close
-        @lockfh = nil
     end
 
     # Answer one command, as the hub would.
@@ -99,9 +116,10 @@ class FakeHub
         code = cmd[0, 2]
         args = cmd[2..].to_s
 
-        # GP is the one command the hub answers unauthenticated, with a
-        # bare 8-digit payload rather than a G/E status.
-        return encode(@state) + 'FFFF' if code == 'GP'
+        # GP and ?Q are the two commands the hub answers without a
+        # password, both with a bare payload rather than a G/E status.
+        return encode(@state | absent)  if code == 'GP'
+        return @ident || 'E01'         if code == '?Q'
 
         return 'E01' unless args.start_with?(@password)
         rest = args[@password.size..]
@@ -109,21 +127,29 @@ class FakeHub
         sleep @delay if @delay.positive?
 
         case code
-        when 'SP' then @state = decode(rest)             ; 'G'
-        when 'FP' then @state = @flash = decode(rest)    ; 'G'
+        when 'SP' then @state = decode(rest) & real      ; 'G'
+        when 'FP' then @state = @flash = decode(rest) & real ; 'G'
         when 'WP' then @flash = @state                   ; 'G'
-        when 'RD' then @state = @flash                   ; 'G'
+        when 'RD' then @state = @flash = 0
+                       @password = DEFAULT_PASSWORD            ; 'G'
         when 'RH' then @state = @flash                   ; nil
         when 'CP' then @password = rest                  ; 'G'
         else           'E02'
         end
     end
 
-    # Little-endian 16-bit, spelled out rather than packed.  Upper case
-    # because that is what a real hub answers -- observed on an ExSYS
-    # 16-port unit, which replies to GP with e.g. "C4FFFFFF".
-    def encode(v) = format('%02X%02X', v & 0xff, (v >> 8) & 0xff)
-    def decode(s) = s[0, 2].to_i(16) | (s[2, 2].to_i(16) << 8)
+    # Little-endian, any width, spelled out rather than packed.  Upper
+    # case because that is what a real hub answers -- observed on an
+    # ExSYS 16-port unit, which replies to GP with "C4FFFFFF".
+    def encode(v)
+        (@width / 2).times.map {|i| format('%02X', (v >> (8 * i)) & 0xff) }
+                    .join
+    end
+
+    def decode(str)
+        str.scan(/\h\h/).each_with_index
+           .sum {|byte, i| byte.to_i(16) << (8 * i) }
+    end
 
     def load
         return if @path.nil? || !File.exist?(@path)

data/test/support/uart.rb

@@ -18,12 +18,29 @@ module UART
         def reset! = @hub = nil
     end
 
-    # Stands in for the File that UART.open normally yields.
+    # Stands in for the File that UART.open normally yields.  Each one
+    # carries its own lock handle, as a real open would, so that two of
+    # them contend instead of sharing one.
     class Serial
-        def initialize(hub) = @hub = hub
-        def flock(mode)     = @hub.flock(mode)
-        def write(cmd)      = @reply = @hub.command(cmd.chomp("\r"))
-        def read            = @reply.nil? ? '' : "#{@reply}\r"
+        def initialize(hub)
+            @hub  = hub
+            @lock = hub.lock_path &&
+                    File.open(hub.lock_path, File::RDWR|File::CREAT, 0o600)
+        end
+
+        def flock(mode)
+            @hub.lock_attempted
+            @lock ? @lock.flock(mode) : 0
+        end
+
+        def write(cmd) = @reply = @hub.command(cmd.chomp("\r"))
+
+        # A real hub ends every reply CR LF -- seen in the hex off the
+        # wire -- so a read to the terminator takes the whole line.
+        def gets(_sep = "\n")
+            @reply.nil? ? nil : "#{@reply}\r\n"
+        end
+        def close      = @lock&.close
     end
 
     def self.open(line, speed = 9600, mode = '8N1')
@@ -34,7 +51,7 @@ module UART
         begin
             yield serial
         ensure
-            hub.unlock
+            serial.close
         end
     end
 end

data/test/test_exsys_usb.rb

@@ -50,19 +50,104 @@ class TestExsysUsb < Minitest::Test
         assert_equal [ 3 ], hub.ports_on
     end
 
-    def test_commit_and_restore
+    def test_commit_saves_the_power_on_state
         exsys_usb('on', '1')
         exsys_usb('commit')
         exsys_usb('on', '2')
-        exsys_usb('restore')
-        assert_equal [ 1 ], hub.ports_on
+        assert_equal [ 1, 2 ], hub.ports_on
+        assert_equal [ 1 ],    hub.flash_ports
     end
 
     def test_commit_flag_writes_through
         exsys_usb('-c', 'on', '4')
         exsys_usb('on', '5')
-        exsys_usb('restore')
-        assert_equal [ 4 ], hub.ports_on
+        assert_equal [ 4, 5 ], hub.ports_on
+        assert_equal [ 4 ],    hub.flash_ports
+    end
+
+    # restore issues RD, the hub's factory reset -- not the inverse of
+    # commit.  Nothing in the protocol reloads the flashed state.
+    def test_restore_is_a_factory_reset
+        exsys_usb('on', '1')
+        exsys_usb('commit')
+        _, err, st = exsys_usb('--yes', 'factory-reset')
+        assert_equal 0, st.exitstatus, err
+        assert_empty hub.ports_on
+        assert_empty hub.flash_ports
+    end
+
+    ## Reading the hub ##################################################
+
+    def test_status_lists_every_port
+        exsys_usb('on', '1', '3')
+        out, _, st = exsys_usb('status')
+        assert_equal 0, st.exitstatus
+        assert_equal 16, out.lines.size
+        assert_includes out.lines, "1 on\n"
+        assert_includes out.lines, "2 off\n"
+        assert_includes out.lines, "3 on\n"
+    end
+
+    def test_status_can_be_asked_about_named_ports
+        exsys_usb('on', '3')
+        out, _, = exsys_usb('status', '3', '4')
+        assert_equal "3 on\n4 off\n", out
+    end
+
+    def test_status_refuses_a_port_the_hub_does_not_have
+        _, err, st = exsys_usb('status', '99')
+        assert_equal 1, st.exitstatus
+        assert_match(/invalid port: 99/, err)
+    end
+
+    def test_query_reports_what_the_hub_says_it_is
+        out, _, st = exsys_usb('query')
+        assert_equal 0, st.exitstatus
+        assert_match(/^id:\s+CENTOS$/,   out)
+        assert_match(/^ports:\s+16$/,    out)
+        assert_match(/^firmware:\s+v02$/, out)
+    end
+
+    ## Verbose ##########################################################
+
+    def test_verbose_reports_the_state_after_a_change
+        out, _, = exsys_usb('-v', 'on', '2')
+        assert_includes out.lines, "2 on\n"
+        assert_equal 16, out.lines.size
+    end
+
+    def test_without_verbose_a_change_says_nothing
+        out, _, st = exsys_usb('on', '2')
+        assert_equal 0, st.exitstatus
+        assert_empty out
+    end
+
+    ## Confirming the irreversible ######################################
+
+    def test_reset_refuses_without_yes
+        _, err, st = exsys_usb('reset')
+        assert_equal 1, st.exitstatus
+        assert_match(/--yes/, err)
+    end
+
+    def test_reset_runs_when_meant
+        _, err, st = exsys_usb('--yes', 'reset')
+        assert_equal 0, st.exitstatus, err
+    end
+
+    def test_factory_reset_refuses_without_yes
+        exsys_usb('on', '1')
+        _, err, st = exsys_usb('factory-reset')
+        assert_equal 1, st.exitstatus
+        assert_match(/--yes/, err)
+        assert_equal [ 1 ], hub.ports_on, 'the hub must not have been touched'
+    end
+
+    def test_factory_reset_runs_when_meant
+        exsys_usb('on', '1')
+        _, err, st = exsys_usb('--yes', 'factory-reset')
+        assert_equal 0, st.exitstatus, err
+        assert_empty hub.ports_on
     end
 
     ## Exit status -- regression.  Every failure used to be printed and
@@ -220,6 +305,16 @@ class TestExsysUsb < Minitest::Test
         assert_equal [ 1, 2 ], hub.ports_on
     end
 
+    # Typing the old name must not silently do nothing, nor quietly do
+    # the reset: it must say what the command actually is.
+    def test_the_old_restore_action_explains_itself
+        _, err, st = exsys_usb('restore')
+        assert_equal 1, st.exitstatus
+        assert_match(/renamed factory-reset/, err)
+        assert_match(/factory defaults/,      err)
+        assert_equal [], hub.ports_on
+    end
+
     ## Packaging #########################################################
 
     # Regression: the file carried a shebang but no execute bit, so a

data/test/test_managed_usb.rb

@@ -11,17 +11,37 @@ class TestManagedUSB < Minitest::Test
 
     ## Switching #########################################################
 
-    def test_on_without_argument_powers_every_port
-        @usb.on
+    def test_all_powers_every_port
+        @usb.on(ExSYS::ManagedUSB::ALL)
         assert_equal ExSYS::ManagedUSB::PORTS, @hub.ports_on
     end
 
-    def test_off_without_argument_powers_nothing
-        @usb.on
-        @usb.off
+    def test_all_unpowers_every_port
+        @usb.on(:all)
+        @usb.off(:all)
         assert_empty @hub.ports_on
     end
 
+    # Regression: an empty list used to mean every port, so a caller
+    # splatting a computed list that came back empty switched all
+    # sixteen.  on(*[]) and on() are the same call, so neither can be
+    # allowed through.
+    def test_an_empty_port_list_is_refused_not_taken_as_every_port
+        @usb.on(:all)
+        [ ->{ @usb.on(*[])     }, ->{ @usb.on        },
+          ->{ @usb.off(*[])    }, ->{ @usb.off       },
+          ->{ @usb.toggle(*[]) }, ->{ @usb.toggle    } ].each do |op|
+            err = assert_raises(ArgumentError, &op)
+            assert_match(/no port given/, err.message)
+        end
+        assert_equal ExSYS::ManagedUSB::PORTS, @hub.ports_on,
+                     'the hub must not have been touched'
+    end
+
+    def test_all_cannot_be_mixed_with_port_numbers
+        assert_raises(ArgumentError) { @usb.on(:all, 3) }
+    end
+
     def test_on_and_off_are_restricted_to_the_named_ports
         @usb.on(1, 2, 16)
         assert_equal [ 1, 2, 16 ], @hub.ports_on
@@ -36,8 +56,8 @@ class TestManagedUSB < Minitest::Test
     end
 
     def test_switching_returns_self_so_calls_chain
-        assert_same @usb, @usb.on
-        @usb.on.off(4, 5, 6)
+        assert_same @usb, @usb.on(:all)
+        @usb.on(:all).off(4, 5, 6)
         assert_equal ExSYS::ManagedUSB::PORTS - [ 4, 5, 6 ], @hub.ports_on
     end
 
@@ -141,7 +161,7 @@ class TestManagedUSB < Minitest::Test
     def test_get_on_off_always_carries_both_keys
         assert_equal({ :on => [], :off => ExSYS::ManagedUSB::PORTS },
                      @usb.get(:on_off))
-        @usb.on
+        @usb.on(:all)
         assert_equal({ :on => ExSYS::ManagedUSB::PORTS, :off => [] },
                      @usb.get(:on_off))
         @usb.off(1)
@@ -151,6 +171,7 @@ class TestManagedUSB < Minitest::Test
     # A real hub answers in upper case; accept either, since the reply
     # is only ever fed to pack('H4'), which does not care.
     def test_a_lower_case_reply_decodes_the_same
+        @usb.port_count              # settle ?Q before garbling every reply
         @hub.garbage = 'c4ffffff'
         assert_equal [ 3, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16 ], @usb.get(:on)
         @hub.garbage = 'C4FFFFFF'
@@ -163,24 +184,191 @@ class TestManagedUSB < Minitest::Test
 
     ## Flash and reset ###################################################
 
-    def test_commit_saves_and_restore_brings_back
+    def test_commit_saves_the_state_as_the_power_on_state
         @usb.on(1)
         @usb.commit
-        @usb.on(2)
-        assert_equal [ 1, 2 ], @hub.ports_on
-        @usb.restore
-        assert_equal [ 1 ], @hub.ports_on
+        assert_equal [ 1 ], @hub.flash_ports
+    end
+
+    # RD is the hub's "restore factory defaults", not the inverse of
+    # commit: there is no command that reloads the flashed state, the
+    # hub applies it at power-on by itself.  Modelled from the vendor's
+    # own documentation -- running it against hardware would drop every
+    # port on the bench and reset the password.
+    ## Describing the hub ###############################################
+
+    def test_query_reports_id_ports_and_firmware
+        assert_equal({ :id => 'CENTOS', :ports => 16, :firmware => 'v02',
+                       :raw => 'CENTOS000516v02' }, @usb.query)
+    end
+
+    def test_query_needs_no_password
+        usb = ExSYS::ManagedUSB.new('/dev/null', 'wrong')
+        assert_equal 16, usb.query[:ports]
+    end
+
+    # The hub is asked how many ports it has before it is read, not
+    # somewhere in the middle: a trace of any port operation reads the
+    # same way, and an invalid port is refused without touching it.
+    def test_the_query_leads_and_happens_once
+        @usb.on(1)
+        assert_equal %w[?Q GP SP], (@hub.log.map {|c| c[0, 2] })
+
+        @hub.log.clear
+        @usb.off(2)
+        assert_equal %w[GP SP], (@hub.log.map {|c| c[0, 2] })
+    end
+
+    def test_an_invalid_port_is_refused_before_the_hub_is_read
+        assert_raises(ArgumentError) { @usb.on(99) }
+        assert_equal %w[?Q], (@hub.log.map {|c| c[0, 2] })
+    end
+
+    def test_port_count_is_asked_once_and_remembered
+        3.times { @usb.port_count }
+        assert_equal 1, @hub.log.count('?Q')
+    end
+
+    # Firmware that does not know ?Q answers an error, and the count
+    # falls back to what the state word can address.
+    def test_port_count_falls_back_when_the_hub_refuses_the_query
+        @hub.ident = nil                        # answers E01
+        assert_equal ExSYS::ManagedUSB::PORTS.size, @usb.port_count
+        assert_match(/will not answer/, @dbg.string)
+    end
+
+    # A reply that arrives but cannot be read is a different thing from
+    # a refusal, and must not be guessed at: on a wider hub a guess of
+    # sixteen would leave its upper ports untouched while reporting
+    # success.
+    def test_an_unreadable_query_reply_does_not_become_a_guess
+        @hub.ident = 'CENTOS-garbled'
+        assert_raises(ExSYS::ManagedUSB::Error) { @usb.port_count }
+        assert_raises(ExSYS::ManagedUSB::Error) { @usb.on(:all) }
+    end
+
+    # The firmware is whatever follows the count, not a bare number:
+    # a hub reporting v1.02 must not fall back to a guessed count.
+    def test_a_dotted_firmware_version_still_parses
+        @hub.ident = 'CENTOS000532v1.02'
+        assert_equal 32,      @usb.query[:ports]
+        assert_equal 'v1.02', @usb.query[:firmware]
+        assert_equal 32,      @usb.port_count
+    end
+
+    def test_an_unparseable_query_reply_is_an_error
+        @hub.ident = 'wat'
+        err = assert_raises(ExSYS::ManagedUSB::Error) { @usb.query }
+        assert_match(/unexpected query reply/, err.message)
+    end
+
+    # ALL means every port the hub says it has.  Confirmed against the
+    # vendor tool, which reads the same field and reports 4, 8, 16 or
+    # 32 ports from it.
+    def test_all_covers_exactly_the_ports_the_hub_reports
+        @hub.ident = 'CENTOS000504v02'          # a hub with 4 ports
+        @usb.on(:all)
+        assert_equal [ 1, 2, 3, 4 ], @hub.ports_on
+        assert_equal [ 1, 2, 3, 4 ], @usb.ports
+    end
+
+    def test_a_port_the_hub_does_not_have_is_refused
+        @hub.ident = 'CENTOS000504v02'
+        assert_raises(ArgumentError) { @usb.on(5) }
+    end
+
+    ## Hubs that are not sixteen ports ##################################
+
+    # Regression: the state word's upper half was written as a literal
+    # 'ffff' rather than carried back from the read.  On a 16-port hub
+    # those bits are ports that do not exist and it went unnoticed; on
+    # a 32-port hub it powered ports 17..32 on every single operation.
+    def test_a_wider_hub_does_not_have_its_upper_ports_driven
+        UART.hub = wide = FakeHub.new(ports: 32, width: 8)
+        usb = ExSYS::ManagedUSB.new('/dev/null')
+
+        usb.on(1)
+        assert_equal [ 1 ], wide.ports_on
+    end
+
+    def test_a_wider_hub_can_use_all_of_its_ports
+        UART.hub = wide = FakeHub.new(ports: 32, width: 8)
+        usb = ExSYS::ManagedUSB.new('/dev/null')
+
+        assert_equal 32, usb.port_count
+        usb.on(:all)
+        assert_equal (1..32).to_a, wide.ports_on
+        usb.off(20)
+        assert_equal (1..32).to_a - [ 20 ], wide.ports_on
+    end
+
+    def test_a_narrower_hub_reports_only_the_ports_it_has
+        UART.hub = small = FakeHub.new(ports: 4, width: 8)
+        usb = ExSYS::ManagedUSB.new('/dev/null')
+
+        assert_equal [ 1, 2, 3, 4 ], usb.ports
+        usb.on(:all)
+        assert_equal [ 1, 2, 3, 4 ], small.ports_on
+        assert_equal({ 1 => true, 2 => true, 3 => true, 4 => true },
+                     usb.get)
+        assert_raises(ArgumentError) { usb.on(5) }
+    end
+
+    # The ports it does not have read as 1, and must be written back
+    # that way rather than cleared.
+    def test_absent_ports_are_carried_back_untouched
+        UART.hub = small = FakeHub.new(ports: 4, width: 8)
+        usb = ExSYS::ManagedUSB.new('/dev/null')
+
+        usb.on(1)
+        # Little-endian: ports 1..8 in the first byte, so port 1 on with
+        # ports 5..32 absent and reading 1 is F1 FF FF FF.
+        assert_equal 'F1FFFFFF', small.log.last[-8..],
+                     'absent ports written back as read'
+    end
+
+    ## Factory reset #####################################################
+
+    def test_the_old_restore_name_is_a_tombstone
+        err = assert_raises(NoMethodError) { @usb.restore }
+        assert_match(/renamed factory_reset/, err.message)
+        assert_match(/not the inverse of commit/, err.message)
+    end
+
+    def test_factory_reset_refuses_unless_it_is_confirmed
+        @usb.on(:all)
+        err = assert_raises(ArgumentError) { @usb.factory_reset }
+        assert_match(/confirm: true/, err.message)
+        assert_equal ExSYS::ManagedUSB::PORTS, @hub.ports_on,
+                     'the hub must not have been touched'
+    end
+
+    def test_restore_is_a_factory_reset
+        @usb.on(1)
+        @usb.commit
+        @usb.on(:all)
+        @usb.factory_reset(confirm: true)
+        assert_empty @hub.ports_on,  'every port dropped'
+        assert_empty @hub.flash_ports, 'the power-on state went too'
+        assert_equal FakeHub::DEFAULT_PASSWORD, @hub.password
     end
 
     def test_on_with_commit_writes_through_to_flash
         @usb.on(3, commit: true)
         @usb.on(4)
-        @usb.restore
-        assert_equal [ 3 ], @hub.ports_on
+        assert_equal [ 3, 4 ], @hub.ports_on
+        assert_equal [ 3 ],    @hub.flash_ports
     end
 
     def test_reset_expects_no_reply
-        assert_same @usb, @usb.reset
+        assert_same @usb, @usb.reset(confirm: true)
+    end
+
+    def test_reset_refuses_unless_it_is_confirmed
+        @usb.on(:all)
+        err = assert_raises(ArgumentError) { @usb.reset }
+        assert_match(/confirm: true/, err.message)
+        refute_includes @hub.log.map {|c| c[0, 2] }, 'RH'
     end
 
     ## Password ##########################################################
@@ -257,14 +445,16 @@ class TestManagedUSB < Minitest::Test
     # Regression: a read-modify-write used to close the line between the
     # GP and the SP, letting another process slip in between the two.
     def test_read_modify_write_holds_the_line_open
+        @usb.port_count                        # the one-off ?Q, out of the way
+        @hub.log.clear
         @usb.on(1)
-        assert_equal 1, @hub.opens
         assert_equal 2, @hub.log.size          # GP then SP, one session
+        assert_equal %w[GP SP], (@hub.log.map {|c| c[0, 2] })
     end
 
     def test_set_holds_the_line_open_too
         @usb.set({ 1 => true })
-        assert_equal 1, @hub.opens
+        assert_equal 1, @hub.opens             # ?Q, GP and SP all inside it
     end
 
     def test_the_line_is_opened_as_the_hub_expects
@@ -280,6 +470,66 @@ class TestManagedUSB < Minitest::Test
         assert_equal 1, @hub.locks
     end
 
+    # Regression: EBADF and EINVAL were swallowed alongside the genuine
+    # "this platform will not lock this" errors.  Both mean a bug here,
+    # and swallowing one runs unlocked while reporting success.
+    def test_an_unexpected_lock_error_is_not_swallowed
+        @hub.lock_error = Errno::EBADF
+        assert_raises(Errno::EBADF) { @usb.on(1) }
+    end
+
+    ## Sessions #########################################################
+
+    def test_session_yields_the_hub_and_returns_the_block_value
+        result = @usb.session {|h| assert_same @usb, h; :done }
+        assert_equal :done, result
+    end
+
+    def test_one_session_holds_one_line_for_every_call_inside_it
+        @usb.session do
+            @usb.get
+            @usb.on(1)
+            @usb.off(1)
+        end
+        assert_equal 1, @hub.opens
+        assert_equal 1, @hub.locks
+    end
+
+    def test_without_a_session_each_call_opens_its_own_line
+        @usb.get
+        @usb.on(1)
+        assert_equal 2, @hub.opens
+    end
+
+    def test_a_session_releases_the_line_even_when_the_block_raises
+        assert_raises(RuntimeError) { @usb.session { raise 'boom' } }
+        @usb.on(1)                       # must open afresh, not reuse
+        assert_equal 2, @hub.opens
+        assert_equal [ 1 ], @hub.ports_on
+    end
+
+    # Regression: the open line was plain instance state, so a second
+    # thread either borrowed a line it held no lock on -- losing one
+    # thread's change -- or had it closed underneath it by the first
+    # thread's ensure, which surfaced as a NoMethodError on nil.
+    def test_two_threads_never_share_one_line
+        Dir.mktmpdir('exsys-threads') do |dir|
+            fake = FakeHub.new(path: File.join(dir, 'hub'),
+                               lock: File.join(dir, 'lock'), delay: 0.2)
+            UART.hub = fake
+            usb = ExSYS::ManagedUSB.new('/dev/null')
+
+            a = Thread.new { usb.on(1) }
+            sleep 0.1                    # B enters while A holds the line
+            b = Thread.new { usb.on(2) }
+            [ a, b ].each(&:join)
+
+            assert_equal 2, fake.opens, 'each thread opens its own line'
+            assert_equal 2, fake.locks, 'each thread takes its own lock'
+            assert_equal [ 1, 2 ], fake.ports_on
+        end
+    end
+
     # A platform that will not lock a character device must not make the
     # tool unusable; it degrades to unlocked and says so.
     def test_an_unlockable_line_degrades_rather_than_failing

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: exsys
 version: !ruby/object:Gem::Version
-  version: '0.6'
+  version: '1.0'
 platform: ruby
 authors:
 - Stéphane D'Alu