variable 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e2c6b1e6250c9d32d21b5e087df105f75b1f16843cc5ed982cf4d29c6ace1e80
+  data.tar.gz: a81dbcafed634cca911644f44c11d68d8fd13d75baa34ab53dcd4ac27cb7b534
+SHA512:
+  metadata.gz: 71325915d362933079d97a368c19dfa7e6a5f749ee5f392d4b9e263cac14aae416757456613cb3d26b2f88098218e996026b7ae094f7dc1593abdf7864fdb00c
+  data.tar.gz: 554c196e7a3c40d15b35217179b358c23f3aaebdaaab1f456389a13a5f6bd687d70efa3eafce2e14318e6488d5df26e51f392ced35aa35769cac219f5aa5856a

data/.github/workflows/main.yaml

@@ -0,0 +1,68 @@
+name: CI
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+    branches: [master]
+
+env:
+  BUNDLE_PATH: vendor/bundle
+
+jobs:
+  build:
+    name: setup
+    strategy:
+      matrix:
+        ruby: [2.5, 2.6, 2.7, jruby]
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v2
+    - uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: ${{ matrix.ruby }}
+    - uses: actions/cache@v1
+      with:
+        path: vendor/bundle
+        key: ${{ matrix.ruby }}-${{ hashFiles('Gemfile.lock') }}-3
+    - name: bundle
+      run: bundle --jobs 4 --retry 3
+  spec:
+    needs: build
+    strategy:
+      matrix:
+        ruby: [2.5, 2.6, 2.7, jruby]
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v2
+    - uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: ${{ matrix.ruby }}
+    - uses: actions/cache@v1
+      with:
+        path: vendor/bundle
+        key: ${{ matrix.ruby }}-${{ hashFiles('Gemfile.lock') }}-3
+    - run: bundle exec rspec spec
+  mutant:
+    needs: build
+    strategy:
+      matrix:
+        ruby: [2.5, 2.6, 2.7]
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v2
+    - uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: ${{ matrix.ruby }}
+    - uses: actions/cache@v1
+      with:
+        path: vendor/bundle
+        key: ${{ matrix.ruby }}-${{ hashFiles('Gemfile.lock') }}-3
+    - run: |
+        bundle exec mutant \
+        --include lib      \
+        --require variable \
+        --use rspec        \
+        --zombie           \
+        --                 \
+        'Variable*'

data/.rspec

@@ -0,0 +1,5 @@
+--color
+--format progress
+--order random
+--require spec_helper
+--warnings

data/Gemfile

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec
+
+group :development do
+  gem 'mutant',       '~> 0.8.24'
+  gem 'mutant-rspec', '~> 0.8.24'
+end
+
+gem(
+  'devtools',
+  git: 'https://github.com/mbj/devtools.git',
+  ref: '26ba0a1053e6cf7b79fc72d513a73457f9a38ead'
+)

data/Gemfile.lock

@@ -0,0 +1,179 @@
+GIT
+  remote: https://github.com/mbj/devtools.git
+  revision: 26ba0a1053e6cf7b79fc72d513a73457f9a38ead
+  ref: 26ba0a1053e6cf7b79fc72d513a73457f9a38ead
+  specs:
+    devtools (0.1.23)
+      abstract_type (~> 0.0.7)
+      adamantium (~> 0.2.0)
+      anima (~> 0.3.0)
+      concord (~> 0.1.5)
+      flay (~> 2.12.0)
+      flog (~> 4.6.2)
+      procto (~> 0.0.3)
+      rake (~> 12.3.0)
+      reek (~> 5.3.0)
+      rspec (~> 3.8.0)
+      rspec-core (~> 3.8.0)
+      rspec-its (~> 1.2.0)
+      rubocop (~> 0.61.1)
+      simplecov (~> 0.16.1)
+      yard (~> 0.9.16)
+      yardstick (~> 0.9.9)
+
+PATH
+  remote: .
+  specs:
+    variable (0.0.1)
+      equalizer (~> 0.0.11)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    abstract_type (0.0.7)
+    adamantium (0.2.0)
+      ice_nine (~> 0.11.0)
+      memoizable (~> 0.4.0)
+    anima (0.3.1)
+      abstract_type (~> 0.0.7)
+      adamantium (~> 0.2)
+      equalizer (~> 0.0.11)
+    ast (2.4.0)
+    axiom-types (0.1.1)
+      descendants_tracker (~> 0.0.4)
+      ice_nine (~> 0.11.0)
+      thread_safe (~> 0.3, >= 0.3.1)
+    codeclimate-engine-rb (0.4.1)
+      virtus (~> 1.0)
+    coercible (1.0.0)
+      descendants_tracker (~> 0.0.1)
+    concord (0.1.5)
+      adamantium (~> 0.2.0)
+      equalizer (~> 0.0.9)
+    descendants_tracker (0.0.4)
+      thread_safe (~> 0.3, >= 0.3.1)
+    diff-lcs (1.3)
+    docile (1.3.2)
+    equalizer (0.0.11)
+    erubis (2.7.0)
+    flay (2.12.1)
+      erubis (~> 2.7.0)
+      path_expander (~> 1.0)
+      ruby_parser (~> 3.0)
+      sexp_processor (~> 4.0)
+    flog (4.6.4)
+      path_expander (~> 1.0)
+      ruby_parser (~> 3.1, > 3.1.0)
+      sexp_processor (~> 4.8)
+    ice_nine (0.11.2)
+    jaro_winkler (1.5.4)
+    json (2.3.0)
+    kwalify (0.7.2)
+    memoizable (0.4.2)
+      thread_safe (~> 0.3, >= 0.3.1)
+    morpher (0.2.6)
+      abstract_type (~> 0.0.7)
+      adamantium (~> 0.2.0)
+      anima (~> 0.3.0)
+      ast (~> 2.2)
+      concord (~> 0.1.5)
+      equalizer (~> 0.0.9)
+      ice_nine (~> 0.11.0)
+      procto (~> 0.0.2)
+    mutant (0.8.24)
+      abstract_type (~> 0.0.7)
+      adamantium (~> 0.2.0)
+      anima (~> 0.3.0)
+      ast (~> 2.2)
+      concord (~> 0.1.5)
+      diff-lcs (~> 1.3)
+      equalizer (~> 0.0.9)
+      ice_nine (~> 0.11.1)
+      memoizable (~> 0.4.2)
+      morpher (~> 0.2.6)
+      parser (~> 2.5.1)
+      procto (~> 0.0.2)
+      regexp_parser (~> 1.2)
+      unparser (~> 0.4.2)
+    mutant-rspec (0.8.24)
+      mutant (~> 0.8.24)
+      rspec-core (>= 3.4.0, < 4.0.0)
+    parallel (1.19.1)
+    parser (2.5.3.0)
+      ast (~> 2.4.0)
+    path_expander (1.1.0)
+    powerpack (0.1.2)
+    procto (0.0.3)
+    psych (3.1.0)
+    rainbow (3.0.0)
+    rake (12.3.3)
+    reek (5.3.2)
+      codeclimate-engine-rb (~> 0.4.0)
+      kwalify (~> 0.7.0)
+      parser (>= 2.5.0.0, < 2.7, != 2.5.1.1)
+      psych (~> 3.1.0)
+      rainbow (>= 2.0, < 4.0)
+    regexp_parser (1.7.0)
+    rspec (3.8.0)
+      rspec-core (~> 3.8.0)
+      rspec-expectations (~> 3.8.0)
+      rspec-mocks (~> 3.8.0)
+    rspec-core (3.8.2)
+      rspec-support (~> 3.8.0)
+    rspec-expectations (3.8.6)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.8.0)
+    rspec-its (1.2.0)
+      rspec-core (>= 3.0.0)
+      rspec-expectations (>= 3.0.0)
+    rspec-mocks (3.8.2)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.8.0)
+    rspec-support (3.8.3)
+    rubocop (0.61.1)
+      jaro_winkler (~> 1.5.1)
+      parallel (~> 1.10)
+      parser (>= 2.5, != 2.5.1.1)
+      powerpack (~> 0.1)
+      rainbow (>= 2.2.2, < 4.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (~> 1.4.0)
+    ruby-progressbar (1.10.1)
+    ruby_parser (3.14.2)
+      sexp_processor (~> 4.9)
+    sexp_processor (4.14.1)
+    simplecov (0.16.1)
+      docile (~> 1.1)
+      json (>= 1.8, < 3)
+      simplecov-html (~> 0.10.0)
+    simplecov-html (0.10.2)
+    thread_safe (0.3.6)
+    unicode-display_width (1.4.1)
+    unparser (0.4.2)
+      abstract_type (~> 0.0.7)
+      adamantium (~> 0.2.0)
+      concord (~> 0.1.5)
+      diff-lcs (~> 1.3)
+      equalizer (~> 0.0.9)
+      parser (>= 2.3.1.2, < 2.6)
+      procto (~> 0.0.2)
+    virtus (1.0.5)
+      axiom-types (~> 0.1)
+      coercible (~> 1.0)
+      descendants_tracker (~> 0.0, >= 0.0.3)
+      equalizer (~> 0.0, >= 0.0.9)
+    yard (0.9.24)
+    yardstick (0.9.9)
+      yard (~> 0.8, >= 0.8.7.2)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  devtools!
+  mutant (~> 0.8.24)
+  mutant-rspec (~> 0.8.24)
+  variable!
+
+BUNDLED WITH
+   2.1.4

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2020 Markus Schirp
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,5 @@
+![CI](https://github.com/mbj/variable/workflows/CI/badge.svg)
+
+# variable
+
+Ruby concurrency variables inspired by Haskells IVar and MVar.

data/config/devtools.yml

@@ -0,0 +1,2 @@
+---
+unit_test_timeout: 0.5

data/lib/variable.rb

@@ -0,0 +1,322 @@
+# frozen_string_literal: true
+
+require 'equalizer'
+
+# Lightweight concurrency variables
+#
+# These are inspired by Haskells MVar and IVar types.
+class Variable
+  EMPTY = Class.new do
+    const_set(:INSPECT, 'Variable::EMPTY')
+  end.new.freeze
+
+  TIMEOUT = Class.new do
+    const_set(:INSPECT, 'Variable::TIMEOUT')
+  end.new.freeze
+
+  # Result of operation that may time out
+  class Result
+    include Equalizer.new(:value)
+    attr_reader :value
+
+    # Initialize result
+    #
+    # @return [undefined]
+    def initialize(value)
+      @value = value
+      freeze
+    end
+
+    # Test if take resulted in a timeout
+    #
+    # @return [Boolean]
+    #
+    # @api private
+    def timeout?
+      instance_of?(Timeout)
+    end
+
+    # Instance returned on timeouts
+    class Timeout < self
+      INSTANCE = new(nil)
+
+      # Construct new object
+      #
+      # @return [Timeout]
+      def self.new
+        INSTANCE
+      end
+    end # Timeout
+
+    # Instance returned without timeouts
+    class Value < self
+    end # Value
+  end # Result
+
+  private_constant(*constants(false))
+
+  module Timer
+    # Monotonic elapsed time of block execution
+    #
+    # @return [Float]
+    def self.elapsed
+      start = now
+      yield
+      now - start
+    end
+
+    # The now monotonic time
+    #
+    # @return [Float]
+    def self.now
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+    private_class_method :now
+  end # Timer
+
+  # Initialize object
+  #
+  # @param [Object] value
+  #   the initial value
+  #
+  # @return [undefined]
+  def initialize(condition_variable:, mutex:, value: EMPTY)
+    @full  = condition_variable.new
+    @mutex = mutex.new
+    @value = value
+  end
+
+  # Take value, block on empty
+  #
+  # @return [Object]
+  def take
+    synchronize do
+      wait_full
+      perform_take
+    end
+  end
+
+  # Take value, with timeout
+  #
+  # @param [Float] Timeout
+  #
+  # @return [Result::Timeout]
+  #   in case take resulted in a timeout
+  #
+  # @return [Result::Value]
+  #   in case take resulted in a value
+  def take_timeout(timeout)
+    synchronize do
+      if wait_timeout(@full, timeout, &method(:full?))
+        Result::Timeout.new
+      else
+        Result::Value.new(perform_take)
+      end
+    end
+  end
+
+  # Read value, block on empty
+  #
+  # @return [Object]
+  #   the variable value
+  def read
+    synchronize do
+      wait_full
+      @value
+    end
+  end
+
+  # Try put value into the variable, non blocking
+  #
+  # @param [Object] value
+  #
+  # @return [self]
+  def try_put(value)
+    synchronize do
+      perform_put(value) if empty?
+    end
+
+    self
+  end
+
+  # Execute block with value, blocking
+  #
+  # @yield [Object]
+  #
+  # @return [Object]
+  #   the blocks return value
+  def with
+    synchronize do
+      wait_full
+      yield @value
+    end
+  end
+
+private
+
+  # Perform the put
+  #
+  # @param [Object] value
+  def perform_put(value)
+    (@value = value).tap { @full.signal }
+  end
+
+  # Execute block under mutex
+  #
+  # @return [self]
+  def synchronize(&block)
+    @mutex.synchronize(&block)
+  end
+
+  # Wait for block predicate
+  #
+  # @param [ConditionVariable] event
+  #
+  # @return [undefined]
+  def wait(event)
+    event.wait(@mutex) until yield
+  end
+
+  # Wait with timeout for block predicate
+  #
+  # @param [ConditionVariable] event
+  #
+  # @return [Boolean]
+  #   if wait was terminated due a timeout
+  #
+  # @return [undefined]
+  #   otherwise
+  def wait_timeout(event, timeout)
+    loop do
+      break true if timeout <= 0
+      break if yield
+      timeout -= Timer.elapsed { event.wait(@mutex, timeout) }
+    end
+  end
+
+  # Wait till mvar is full
+  #
+  # @return [undefined]
+  def wait_full
+    wait(@full, &method(:full?))
+  end
+
+  # Test if state is full
+  #
+  # @return [Boolean]
+  def full?
+    !empty?
+  end
+
+  # Test if state is empty
+  #
+  # @return [Boolean]
+  def empty?
+    @value.equal?(EMPTY)
+  end
+
+  # Shared variable that can be written at most once
+  #
+  # ignore :reek:InstanceVariableAssumption
+  class IVar < self
+
+    # Exception raised on ivar errors
+    class Error < RuntimeError; end
+
+    # Put value, raises if already full
+    #
+    # @param [Object] value
+    #
+    # @return [self]
+    #
+    # @raise Error
+    #   if already full
+    def put(value)
+      synchronize do
+        fail Error, 'is immutable' if full?
+        perform_put(value)
+      end
+
+      self
+    end
+
+    # Populate and return value, use block to compute value if empty
+    #
+    # The block is guaranteed to be executed at max once.
+    #
+    # Subsequent reads are guaranteed to return the block value.
+    #
+    # @return [Object]
+    def populate_with
+      return @value if full?
+
+      synchronize do
+        perform_put(yield) if empty?
+      end
+
+      @value
+    end
+
+  private
+
+    # Perform take operation
+    #
+    # @return [Object]
+    def perform_take
+      @value
+    end
+  end # IVar
+
+  # Shared variable that can be written multiple times
+  #
+  # ignore :reek:InstanceVariableAssumption
+  class MVar < self
+
+    # Initialize object
+    #
+    # @param [Object] value
+    #   the initial value
+    #
+    # @return [undefined]
+    def initialize(condition_variable:, mutex:, value: EMPTY)
+      super
+      @empty = condition_variable.new
+    end
+
+    # Put value, block on full
+    #
+    # @param [Object] value
+    #
+    # @return [self]
+    def put(value)
+      synchronize do
+        wait(@empty, &method(:empty?))
+        perform_put(value)
+      end
+
+      self
+    end
+
+    # Modify value, blocks if empty
+    #
+    # @return [Object]
+    def modify
+      synchronize do
+        wait_full
+        perform_put(yield(@value))
+      end
+    end
+
+  private
+
+    # Empty the variable
+    #
+    # @return [Object]
+    def perform_take
+      @value.tap do
+        @value = EMPTY
+        @empty.signal
+      end
+    end
+  end # MVar
+end # Variable