ractor-tmvar 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bd148e7f28224c4301b6ec77b004a483722f53b4fdd35d3e69886d06358db39d
-  data.tar.gz: c6b21f4ce16240b9d5912dc6528feeb5cddcb0bac6d8dc81ea8cd0cbd0bd1ee5
+  metadata.gz: 6f3245eebf48796294d345ac5d97677c3f536347f87a204555223781cec1a87d
+  data.tar.gz: 3bf7ca844e8556db49d981b2d50c6e00867927f70348d59242220b66d0e20a59
 SHA512:
-  metadata.gz: 7272a5419621fae9ef87a3cbfd895b9a21d6429b009bb6a3af32a56c62d07a6583e7c86e4f8438e1859055755644f8e2e35ccd8f244f35a742a627b634d579d8
-  data.tar.gz: '08abed6a02c3e4832ef99ca5139cf625a85e66559482758371f380fa590669dc7983e0ca14896a01514a1a474254f207a8ecb7987a65029f7fbbecb7e7f0363d'
+  metadata.gz: b30e17fdb2e91c2aa60e83edf47098926a017a63a192a409545116ef7ec605ab2203361f00862de5e8f2e443058dc3c7111b69a77bf4373d9f718e74faff5c1c
+  data.tar.gz: 567905c4e3ae0b351a0ecaaa69b97a5de09d77e7047da0e07cee7e45818251097e2e12bf32e3ebf173bfff48ccf3dada4ba40c29ad153a87da2176028f098058

data/.github/workflows/build-gem.yml

@@ -0,0 +1,54 @@
+name: Build and attest gem
+
+on:
+  workflow_call:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+      attestations: write
+    steps:
+      - name: Check out tagged source
+        uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6
+        with:
+          ref: ${{ github.sha }}
+          persist-credentials: false
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@e81a8fa391b11a595c1b7ed84177cc0fe02faf83 # v1
+        with:
+          ruby-version: '4.0'
+          bundler-cache: true
+
+      - name: Check release tag matches gem version
+        run: |
+          ruby -r ./lib/ractor/tmvar/version -e '
+            expected = "refs/tags/v#{Ractor::TMVar::VERSION}"
+            abort "Expected #{expected}, got #{ENV.fetch("GITHUB_REF")}" unless ENV.fetch("GITHUB_REF") == expected
+          '
+
+      - name: Run tests and lint
+        run: bundle exec rake
+
+      - name: Build gem
+        run: |
+          mkdir -p pkg
+          gem build ractor-tmvar.gemspec --output "pkg/ractor-tmvar-${GITHUB_REF_NAME#v}.gem"
+
+      - name: Attest gem provenance
+        uses: actions/attest@1e69f48acb82d1966a394da916b4c1698aa569d6 # v4
+        with:
+          subject-path: pkg/*.gem
+
+      - name: Save gem
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: ractor-tmvar-${{ github.ref_name }}
+          path: pkg/*.gem
+          if-no-files-found: error

data/.github/workflows/release.yml

@@ -0,0 +1,17 @@
+name: Build release gem
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    permissions:
+      contents: read
+      id-token: write
+      attestations: write
+    uses: ./.github/workflows/build-gem.yml

data/.gitignore

@@ -7,3 +7,6 @@
 /spec/reports/
 /tmp/
 /vendor/
+.pi
+.env
+.env.local

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    ractor-tmvar (0.3.0)
+    ractor-tmvar (0.4.0)
       ractor-sharing (~> 0.3.0)
 
 GEM
@@ -69,7 +69,7 @@ CHECKSUMS
   prism (1.9.0) sha256=7b530c6a9f92c24300014919c9dcbc055bf4cdf51ec30aed099b06cd6674ef85
   racc (1.8.1) sha256=4a7f6929691dbec8b5209a0b373bc2614882b55fc5d2e447a21aaa691303d62f
   ractor-sharing (0.3.0) sha256=9adb2f899e4e38f477a2d3c02368e8ff40be96b119172312253338ee1e22f63f
-  ractor-tmvar (0.3.0)
+  ractor-tmvar (0.4.0)
   rainbow (3.1.1) sha256=039491aa3a89f42efa1d6dec2fc4e62ede96eb6acd95e52f1ad581182b79bc6a
   rake (13.4.2) sha256=cb825b2bd5f1f8e91ca37bddb4b9aaf345551b4731da62949be002fa89283701
   regexp_parser (2.13.1) sha256=5aedb6b7c35688f51e86eef17a15374dfd287c83f4ca644b2c5f3ec50a33b44b

data/README.md

@@ -47,11 +47,74 @@ tv1.read #=> 100
 tv2.read #=> 200
 ```
 
+`Ractor::TMVar.new` creates an empty variable, while `Ractor::TMVar.new(value)` or
+`Ractor::TMVar.new_filled(value)` creates a variable already containing `value`.
+`nil` can be stored as a normal value:
+
+```ruby
+tv = Ractor::TMVar.new_filled(nil)
+tv.empty? #=> false
+tv.read   #=> nil
+```
+
+### Transactional operations
+
+`take`, `put`, `swap`, `try_take`, and `try_put` must be called inside `Ractor.atomically`. `read` and
+`empty?` can be called outside of a transaction.
+
+```ruby
+tv = Ractor::TMVar.new
+Ractor.atomically { tv.put(42) }
+Ractor.atomically { tv.take } #=> 42
+```
+
+### Non-blocking try operations
+
+`try_take` and `try_read` never retry. Without a block, they return the stored
+value, or `nil` when empty. With a block, when the variable is
+empty they return `nil` without calling the block. When it is full they yield the
+stored value and return the block's result, so a stored `nil` can be told apart
+from an empty variable. `try_take` empties the variable before yielding;
+`try_read` leaves it full.
+
+```ruby
+tv = Ractor::TMVar.new(5)
+
+tv.try_read { |v| v * 2 } #=> 10
+tv.read                   #=> 5
+
+Ractor.atomically { tv.try_take { |v| v * 2 } } #=> 10
+tv.empty?                                        #=> true
+
+empty = Ractor::TMVar.new
+Ractor.atomically { empty.try_take { |v| [v] } } #=> nil (block not called)
+
+filled_with_nil = Ractor::TMVar.new_filled(nil)
+filled_with_nil.try_read { |v| [v] } #=> [nil]
+```
+
+`try_put` returns `true` when it stored the value and `false` when the variable
+was already full.
+
+```ruby
+tv = Ractor::TMVar.new
+Ractor.atomically { tv.try_put(1) } #=> true
+Ractor.atomically { tv.try_put(2) } #=> false
+```
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+To install this gem onto your local machine, run `bundle exec rake install`.
+
+## Verifying gem provenance
+
+Verify a downloaded gem's build provenance attestation with the GitHub CLI:
+
+```sh
+gh attestation verify ractor-tmvar-0.3.0.gem -R yoshitsugu/ractor-tmvar
+```
 
 ## Contributing
 

data/lib/ractor/tmvar/version.rb

@@ -2,6 +2,6 @@
 
 class Ractor
   class TMVar
-    VERSION = "0.3.0"
+    VERSION = "0.4.0"
   end
 end

data/lib/ractor/tmvar.rb

@@ -1,134 +1,229 @@
 # frozen_string_literal: true
 
 require "ractor/tvar"
+require_relative "tmvar/version"
 
 class Ractor
-  # TMVar for Ractor inspired by Haskell's TMVar based on Ractor::TVar.
+  # Transactional MVar-like variable for Ractor, inspired by Haskell's
+  # +Control.Concurrent.STM.TMVar+ and built on Ractor::TVar.
+  #
+  # A TMVar is either empty or full. When full it holds a single value.
+  # Reading and writing operations are transactional through {Ractor.atomically}.
+  #
+  # The implementation stores +nil+ when empty and a single-element array +[value]+
+  # when full, so any Ruby object (including +nil+) can be stored without colliding
+  # with the empty state.
   class TMVar
     #
-    # represents "empty" value for TMVar
+    # Create a new TMVar.
     #
-    EMPTY = :RACTOR_TMVAR_EMPTY
+    # @overload initialize
+    #   Creates an empty TMVar (Haskell's +newEmptyTMVar+).
+    # @overload initialize(value)
+    #   Creates a TMVar filled with +value+ (Haskell's +newTMVar+).
+    #   @param [Object] value value to store. With ractor-sharing 0.3, the value is
+    #     automatically made Ractor-shareable and the passed object is frozen.
+    #     This behavior is provided by the upstream Ractor::TVar, not a TMVar guarantee.
+    #
+    # @raise [ArgumentError] if more than one argument is given.
+    #
+    def initialize(*args)
+      raise ArgumentError, "wrong number of arguments (given #{args.size}, expected 0..1)" if args.size > 1
+
+      @tvar = Ractor::TVar.new(args.empty? ? nil : [args[0]])
+    end
 
     #
-    # initialize TMVar
+    # Create a new TMVar explicitly filled with +value+.
     #
-    # @param [Object] value value to set. With ractor-sharing 0.3, the value is
+    # This is equivalent to +TMVar.new(value)+ but makes the intent clear when the
+    # stored value might be +nil+.
+    #
+    # @param [Object] value value to store. With ractor-sharing 0.3, the value is
     #   automatically made Ractor-shareable and the passed object is frozen.
     #   This behavior is provided by the upstream Ractor::TVar, not a TMVar guarantee.
     #
     # @return [TMVar]
     #
-    def initialize(value = nil)
-      @tvar = Ractor::TVar.new(value)
+    def self.new_filled(value)
+      new(value)
     end
 
     #
-    # get the value and leave the value to "empty"
-    # If the value is already "empty", it will retry the transaction.
-    # @note You need to wrap it by Ractor.atomically even if you only call +take+
-    #       because +TVar#value=+ needs atomically.
+    # Take the value, leaving the TMVar empty.
+    #
+    # If the TMVar is empty, the transaction is retried.
+    #
+    # @note Must be called inside {Ractor.atomically}.
     #
-    # @return [Object] value of internal TVar.
+    # @return [Object] the stored value.
     #
     def take
-      v = @tvar.value
-      raise Ractor::RetryTransaction if v == EMPTY
+      cell = @tvar.value
+      raise Ractor::RetryTransaction if cell.nil?
 
-      @tvar.value = EMPTY
-      v
+      @tvar.value = nil
+      cell[0]
     end
 
     #
-    # try to get the value.
-    # If the value is "empty", it returns nil.
+    # Try to take the value without retrying.
     #
-    # @return [Object] value of internal TVar, only if exists.
+    # If the TMVar is empty, returns +nil+ without calling the block.
+    # If the TMVar is full, empties it, yields the value and returns the block's result.
+    # Without a block, returns the stored value unchanged.
+    # Because the block is called only when full, a stored +nil+ can be told apart
+    # from an empty TMVar.
     #
-    def try_take
-      v = @tvar.value
-      return nil if v == EMPTY
+    # @note Must be called inside {Ractor.atomically}.
+    #
+    # @overload try_take
+    #   @return [Object, nil] the stored value, or +nil+ if empty.
+    # @overload try_take { |value| ... }
+    #   @yieldparam value [Object] the stored value, including +nil+.
+    #   @yieldreturn [Object] the value to return from +try_take+.
+    #   @return [Object, nil] the block's result, or +nil+ if empty.
+    #
+    # @example Take a value without a block
+    #   tv = Ractor::TMVar.new(5)
+    #   Ractor.atomically { tv.try_take } #=> 5
+    #   tv.empty? #=> true
+    #
+    # @example Distinguish a stored nil from an empty TMVar
+    #   tv = Ractor::TMVar.new(nil)
+    #   Ractor.atomically { tv.try_take { |value| [value] } } #=> [nil]
+    #   Ractor.atomically { tv.try_take { |value| [value] } } #=> nil
+    #
+    def try_take(&block)
+      cell = @tvar.value
+      return nil if cell.nil?
 
-      @tvar.value = EMPTY
-      v
+      @tvar.value = nil
+      (block || method(:identity)).call(cell[0])
     end
 
     #
-    # get the value like +take+.
-    # The difference between +take+ and +read+ is +take+ leaves the value blank,
-    # but +read+ not change the value to blank.
+    # Read the value, leaving the TMVar full.
     #
-    # @return [Object] value of internal TVar.
+    # If the TMVar is empty, the transaction is retried.
+    # It can also be called outside {Ractor.atomically}.
+    #
+    # @return [Object] the stored value.
     #
     def read
-      v = @tvar.value
-      raise Ractor::RetryTransaction if v == EMPTY
+      cell = @tvar.value
+      raise Ractor::RetryTransaction if cell.nil?
 
-      v
+      cell[0]
     end
 
     #
-    # read the value like +read+ but it does not retry.
+    # Try to read the value without retrying.
+    #
+    # If the TMVar is empty, returns +nil+ without calling the block.
+    # If the TMVar is full, yields the value and returns the block's result.
+    # Without a block, returns the stored value unchanged.
+    # The TMVar remains full.
+    #
+    # @note Can be called outside {Ractor.atomically}.
     #
-    # @return [Object] value of internal TVar.
+    # @overload try_read
+    #   @return [Object, nil] the stored value, or +nil+ if empty.
+    # @overload try_read { |value| ... }
+    #   @yieldparam value [Object] the stored value, including +nil+.
+    #   @yieldreturn [Object] the value to return from +try_read+.
+    #   @return [Object, nil] the block's result, or +nil+ if empty.
     #
-    def try_read
-      v = @tvar.value
-      v == EMPTY ? nil : v
+    # @example Read or transform a value without removing it
+    #   tv = Ractor::TMVar.new(5)
+    #   tv.try_read #=> 5
+    #   tv.try_read { |value| value * 2 } #=> 10
+    #   tv.read #=> 5
+    #
+    # @example Distinguish a stored nil from an empty TMVar
+    #   Ractor::TMVar.new(nil).try_read { |value| [value] } #=> [nil]
+    #   Ractor::TMVar.new.try_read { |value| [value] } #=> nil
+    #
+    def try_read(&block)
+      cell = @tvar.value
+      return nil if cell.nil?
+
+      (block || method(:identity)).call(cell[0])
     end
 
     #
-    # write the given value.
-    # If the current value is not "empty", it retries the transaction.
+    # Put a value into the TMVar.
+    #
+    # If the TMVar is already full, the transaction is retried.
     #
-    # @param [Object] new_value value to set. With ractor-sharing 0.3, the value is
+    # @note Must be called inside {Ractor.atomically}.
+    #
+    # @param [Object] new_value value to store. With ractor-sharing 0.3, the value is
     #   automatically made Ractor-shareable and the passed object is frozen.
     #   This behavior is provided by the upstream Ractor::TVar, not a TMVar guarantee.
     #
+    # @return [Object] +new_value+.
+    #
     def put(new_value)
-      raise Ractor::RetryTransaction if @tvar.value != EMPTY
+      raise Ractor::RetryTransaction unless @tvar.value.nil?
 
-      @tvar.value = new_value
+      @tvar.value = [new_value]
+      new_value
     end
 
     #
-    # try to put value to TVar's value
-    # If the value is not "empty", it will not retry and only return false.
-    # If it succeed to put, it returns true.
+    # Try to put a value into the TMVar without retrying.
+    #
+    # @note Must be called inside {Ractor.atomically}.
     #
-    # @param [Object] new_value value to set. With ractor-sharing 0.3, the value is
+    # @param [Object] new_value value to store. With ractor-sharing 0.3, the value is
     #   automatically made Ractor-shareable and the passed object is frozen.
     #   This behavior is provided by the upstream Ractor::TVar, not a TMVar guarantee.
     #
+    # @return [Boolean] +true+ if the value was stored, +false+ if the TMVar was full.
+    #
     def try_put(new_value)
-      return false if @tvar.value != EMPTY
+      return false unless @tvar.value.nil?
 
-      @tvar.value = new_value
+      @tvar.value = [new_value]
       true
     end
 
     #
-    # return the value is "empty" or not.
+    # Return whether the TMVar is currently empty.
+    # It can also be called outside {Ractor.atomically}.
     #
-    # @param [Boolean]
+    # @return [Boolean]
     #
     def empty?
-      @tvar.value == EMPTY
+      @tvar.value.nil?
     end
 
     #
-    # get the the value like +get+, and replace the value to the given value if the current value is not "empty"
+    # Replace the stored value and return the previous value.
+    #
+    # If the TMVar is empty, the transaction is retried.
     #
-    # @param [Object] new value to set. With ractor-sharing 0.3, the value is
+    # @note Must be called inside {Ractor.atomically}.
+    #
+    # @param [Object] new_value value to store. With ractor-sharing 0.3, the value is
     #   automatically made Ractor-shareable and the passed object is frozen.
     #   This behavior is provided by the upstream Ractor::TVar, not a TMVar guarantee.
     #
-    def swap(new)
-      v = @tvar.value
-      raise Ractor::RetryTransaction if v == EMPTY
+    # @return [Object] the previous value.
+    #
+    def swap(new_value)
+      cell = @tvar.value
+      raise Ractor::RetryTransaction if cell.nil?
+
+      @tvar.value = [new_value]
+      cell[0]
+    end
+
+    private
 
-      @tvar.value = new
-      v
+    def identity(value)
+      value
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ractor-tmvar
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - yoshitsugu
@@ -30,7 +30,9 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".github/workflows/build-gem.yml"
 - ".github/workflows/main.yml"
+- ".github/workflows/release.yml"
 - ".gitignore"
 - ".rubocop.yml"
 - Gemfile
@@ -65,7 +67,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.3
+rubygems_version: 4.0.20
 specification_version: 4
 summary: Ractor::TMVar
 test_files: []