psyllium 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: fec6f648a7f186a7ec0c885aadbf36b7770a5338453c0b22d903041901b08ea3
+  data.tar.gz: bfdbbc18b3def92c75f9dbc654ddc5878eef182e2b762172519cdda88a45e3dc
+SHA512:
+  metadata.gz: 1b1fd0486f6ca2028f1630fc0ac34e16d6a99f6be152030a14ad225c2c916dbc048f69fe8e7a83d9fc021d9c25edd4a224d2caf1e71e7124be832f83532c544e
+  data.tar.gz: 619214a39896eb66ac91d853ff622112200783d2934464b61edc57c0f045d6b128068f2dbc91b4b49fdd3a912da222bdf0eaacad311a530e8c26cfb1d5822a6c

data/.rubocop.yml

@@ -0,0 +1,28 @@
+plugins:
+  - rubocop-minitest
+  - rubocop-rake
+
+AllCops:
+  TargetRubyVersion: 3.1
+  NewCops: enable
+
+Style/SymbolArray:
+  Enabled: false
+
+Style/TrailingCommaInArguments:
+  Enabled: false
+
+Style/TrailingCommaInHashLiteral:
+  Enabled: false
+
+Style/TrailingCommaInArrayLiteral:
+  Enabled: false
+
+Style/RaiseArgs:
+  Enabled: false
+
+Metrics/BlockLength:
+  Enabled: false
+
+Metrics/MethodLength:
+  Enabled: false

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2025-02-19
+
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,12 @@
+Copyright (C) 2025 Ethan D. Estrada <ethan@misterfidget.com>
+
+Permission to use, copy, modify, and/or distribute this software for any purpose
+with or without fee is hereby granted.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
+FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS
+OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
+TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
+THIS SOFTWARE.

data/README.md

@@ -0,0 +1,134 @@
+# Psyllium: Makes using Ruby Fibers easier
+
+> Psyllium \| SIL-ee-um \|
+>
+> 1. _Dietary_ the seed of a fleawort (especially Plantago psyllium). Mainly
+>    used as a supplement to improve dietary fiber consumption.
+> 2. _Programming_ a Ruby gem to improve the experience of using Ruby Fiber
+>    primitives.
+
+## What is Psyllium?
+
+Psyllium is a library to make it easier to use Ruby Fibers for everyday
+programming.
+
+Ruby version 3 introduced the Fiber Scheduler interface, which makes it easier
+to use Fibers for concurrent programming. However, native Thread objects still
+have several useful methods that Fibers do not have.
+
+The Psyllium library adds many of these methods to the builtin Fiber class such
+as `start`, `join`, `value`, and others to make it easier to replace Thread
+usage with Fiber usage, or to mix and match Thread and Fiber usage without
+concern for which concurrency primitive is being used.
+
+Assuming that a Fiber Scheduler is set, Psyllium Fibers can be used in ways
+similar to Threads, with a similar interface, and with the added benefit of
+much lower memory usage compared to native Threads.
+
+## Why Psyllium?
+
+Psyllium makes it easier to use auto-scheduled fibers and to block on their
+execution.
+
+Before Psyllium, the Fiber interface seemed to be centered around two types of
+usage: it was assumed that Fibers would be used in one of two ways:
+
+1. (Before Ruby 3) Explicitly and manually manipulated using `Fiber.resume`,
+   `Fiber.yield`, and `Fiber.alive?`.
+2. (After Ruby 3) Fired off and forgotten about. In essence, left to the
+   scheduler to deal with. If you want a final value back you must use some
+   separate mechanism to track and retrieve it.
+
+With Psyllium, it is possible to call `join` on a Fiber, just like a Thread.
+Assuming other Fibers are simultaneously scheduled, they will continue
+executing concurrently until the Fiber in question finishes joining.
+
+It is also possible to call `value` to retrieve the final value (or exception)
+returned from the block given to `Fiber.start`, in the exact same way as a
+Thread. And just like with a Thread, calling `value` will first implicitly
+`join` the Fiber. It is also possible to give a timeout limit when calling
+`join` on a Fiber, just like with a Thread.
+
+By using Fibers in this way, instead of Threads, memory usage can be
+significantly reduced. Potentially thousands of Fibers can be spawned and
+joined at a fraction of the memory cost of native Threads.
+
+If your Ruby application directly manipulates Threads or Thread pools, and
+those Threads spend most (or all) of their time just waiting on IO, then
+consider trying Psyllium enhanced Fibers instead of Threads.
+
+## Why _not_ Psyllium?
+
+Circumstances where you shouldn't use Psyllium (or Fibers generally):
+
+1. Your application is compute heavy. It uses Threads that call out to FFI code
+   and release the GVL when doing so (i.e. truly parallel code execution).
+2. If you don't have concurrent code at all (i.e. the code must run serially).
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+```bash
+bundle add psyllium
+```
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+```bash
+gem install psyllium
+```
+
+## Usage
+
+Instead of doing the following in your code:
+
+```ruby
+thread1 = Thread.start { long_running_io_operation_with_result1() }
+thread2 = Thread.start { long_running_io_operation_with_result2() }
+
+thread1.join
+thread2.join
+
+# `value` implicitly calls `join`, so the explicit `join` calls above are
+# not strictly necessary.
+value1 = thread1.value
+value2 = thread2.value
+```
+
+You can now do this:
+
+```ruby
+# Adds new methods to Fiber
+require 'psyllium'
+
+# Calls to `Fiber.start` will fail if no scheduler is set beforehand.
+Fiber.set_scheduler(SomeSchedulerImplementation.new)
+
+fiber1 = Fiber.start { long_running_io_operation_with_result1() }
+fiber2 = Fiber.start { long_running_io_operation_with_result2() }
+
+fiber1.join
+fiber2.join
+
+# `value` implicitly calls `join`, so the explicit `join` calls above are
+# not strictly necessary.
+value1 = fiber1.value
+value2 = fiber2.value
+```
+
+## 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 the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at: <https://github.com/eestrada/psyllium>

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'minitest/test_task'
+
+Minitest::TestTask.create
+
+require 'rubocop/rake_task'
+
+RuboCop::RakeTask.new
+
+task default: %i[test rubocop]

data/lib/psyllium/fiber.rb

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+
+require 'timeout'
+
+module Psyllium
+  # Wrap Exception instances for propagation
+  class ExceptionalCompletionError < FiberError
+    def initialize(expt)
+      @internal_exception = expt
+      super(@internal_exception)
+    end
+
+    def cause
+      @internal_exception
+    end
+  end
+
+  # Holds per-Fiber state for Psyllium operations.
+  class State
+    attr_reader :mutex
+    attr_accessor :started, :joined, :value, :exception
+
+    def initialize
+      @mutex = Thread::Mutex.new
+      @started = false
+      @joined = false
+      @value = nil
+      @exception = nil
+    end
+  end
+
+  # Meant to be used with `extend` on Fiber class.
+  module FiberClassMethods
+    # A new method is used to create Psyllium Fibers for several reasons:
+    #
+    # 1. This ensures that existing behavior for Fibers is not changed.
+    #
+    # 2. Modifying the actual instances variables of Fibers does not work well
+    # with certain schedulers like Async which expect to also wrap the given
+    # block in another block.
+    #
+    # 3. The `start` method is also available on the `Thread` class, so this
+    # makes it easy to change out one for the other.
+    def start(*args, &block)
+      raise ArgumentError.new('No block given') unless block
+
+      Fiber.schedule do
+        state = state_get(create_missing: true)
+        state.mutex.synchronize do
+          state.started = true
+          state.value = block.call(*args)
+        rescue StandardError => e
+          state.exception = e
+        ensure
+          state.joined = true
+        end
+      end
+    end
+
+    def state_get(fiber: Fiber.current, create_missing: false)
+      # Psyllium state is a thread local variable because Fibers cannot (yet)
+      # migrates across threads anyway.
+      #
+      # A `WeakKeyMap` is used so that when a Fiber is garbage collected, the
+      # associated Psyllium::State will be garbage collected as well.
+      state = Thread.current.thread_variable_get(:psyllium_state) || Thread.current.thread_variable_set(
+        :psyllium_state, ObjectSpace::WeakKeyMap.new
+      )
+      create_missing ? (state[fiber] ||= State.new) : state[fiber]
+    end
+  end
+
+  # A module meant to extend the builtin Fiber class to make it easier to use
+  # in a more Thread-like manner.
+  module FiberInstanceMethods
+    # Waits for Fiber to complete, using join, and returns its value. If Fiber
+    # completed with an exception, raises `ExceptionalCompletionError`, with
+    # the original exception as its `cause`.
+    def value
+      join
+      raise ExceptionalCompletionError.new(state.exception) if state.exception
+
+      state.value
+    end
+
+    # Mimic Thread `status` method.
+    #
+    # `"run"` will only be returned if this method is called on
+    # `Fiber.current`.
+    #
+    # `"sleep"` is returned for any Fiber that is `alive?`, but not
+    # `Fiber.current`.
+    #
+    # `nil` is returned if the Fiber completed with an exception.
+    #
+    # `false` is returned if the Fiber completed without exception.
+    #
+    # `"abort"` status is never returned because a Fiber does not have a state
+    # like this that is detectable or observable. If `kill` is called on a
+    # Fiber, the operation will happen immediately; there is not a point in
+    # time where `status` can be called between the call to `kill` and the
+    # point at which the Fiber is killed.
+    def status
+      if self == ::Fiber.current
+        'run'
+      elsif alive?
+        'sleep'
+      elsif state(suppress_error: true)&.exception
+        nil
+      else
+        false
+      end
+    end
+
+    # Mimic Thread `stop?` method.
+    #
+    # Return `true` if sleeping or completed.
+    def stop?
+      status == 'sleep' || !alive?
+    end
+
+    # Wait until execution completes. Return the Fiber instance. If `limit` is
+    # reached, returns `nil` instead.
+    #
+    # `join` may be called more than once.
+    def join(limit = nil) # rubocop:disable Metrics/CyclomaticComplexity,Metrics/AbcSize
+      return self if state.joined
+      raise FiberError.new('Cannot join self') if eql?(::Fiber.current)
+      raise FiberError.new('Cannot join when calling Fiber is blocking') if ::Fiber.current.blocking?
+      raise FiberError.new('Cannot join when called Fiber is blocking') if blocking?
+      raise FiberError.new('Cannot join without Fiber scheduler set') unless ::Fiber.scheduler
+      raise FiberError.new('Cannot join unstarted Fiber') unless state.started
+
+      # Once this mutex finishes synchronizing, that means the initial
+      # calculation is done and we can return `self`, which is the Fiber
+      # instance.
+      Timeout.timeout(limit) { state.mutex.synchronize { self } }
+    rescue Timeout::Error
+      # mimic Thread behavior by returning `nil` on timeout.
+      nil
+    end
+
+    private
+
+    def state(suppress_error: false)
+      fiber_state = self.class.state_get(fiber: self)
+      raise Error.new('No Psyllium state for this fiber') unless fiber_state || suppress_error
+
+      fiber_state
+    end
+  end
+
+  # Inherits from the builtin Fiber class, and adds additional functionality to
+  # make it behave more like a Thread.
+  class Fiber < ::Fiber
+    extend ::Psyllium::FiberClassMethods
+    # This must be prepended so that its implementation of `initialize` is called
+    # first.
+    include ::Psyllium::FiberInstanceMethods
+
+    # The `Fiber.kill` method only exists in later versions of Ruby.
+    if instance_methods.include?(:kill)
+      # Thread has the same aliases
+      alias terminate kill
+      alias exit kill
+    end
+  end
+
+  # TODO: figure out how to do this properly
+  # def self.patch_builtin_fiber!
+  #   return if ::Fiber.is_a?(FiberMethods)
+
+  #   ::Fiber.singleton_class.prepend(FiberMethods)
+  # end
+end
+
+class ::Fiber # rubocop:disable Style/Documentation
+  extend ::Psyllium::FiberClassMethods
+  # This must be prepended so that its implementation of `initialize` is called
+  # first.
+  include ::Psyllium::FiberInstanceMethods
+
+  # The `Fiber.kill` method only exists in later versions of Ruby.
+  if instance_methods.include?(:kill)
+    # Thread has the same aliases
+    alias terminate kill
+    alias exit kill
+  end
+end

data/lib/psyllium/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Psyllium
+  VERSION = '0.1.0'
+end

data/lib/psyllium.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require 'timeout'
+require 'forwardable'
+require_relative 'psyllium/version'
+require_relative 'psyllium/fiber'
+
+# Gem to make it easier to work with Fibers.
+module Psyllium
+end

data/sig/psyllium.rbs

@@ -0,0 +1,4 @@
+module Psyllium
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,56 @@
+--- !ruby/object:Gem::Specification
+name: psyllium
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Ethan Estrada
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2025-03-12 00:00:00.000000000 Z
+dependencies: []
+description:
+email:
+- ethan@misterfidget.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rubocop.yml"
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/psyllium.rb
+- lib/psyllium/fiber.rb
+- lib/psyllium/version.rb
+- sig/psyllium.rbs
+homepage: https://github.com/eestrada/psyllium
+licenses:
+- 0BSD
+metadata:
+  allowed_push_host: https://rubygems.org/
+  homepage_uri: https://github.com/eestrada/psyllium
+  source_code_uri: https://github.com/eestrada/psyllium
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: A Ruby gem making it easier to use Fibers.
+test_files: []