psyllium 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fec6f648a7f186a7ec0c885aadbf36b7770a5338453c0b22d903041901b08ea3
-  data.tar.gz: bfdbbc18b3def92c75f9dbc654ddc5878eef182e2b762172519cdda88a45e3dc
+  metadata.gz: d9b892e948fd116cd3947dad9e699175f45d904d43172152bb9435e8014a923a
+  data.tar.gz: 1c5f06d32d119dfdd165c042bd30954614ddc7ba1d11266a041d58c30b5982b3
 SHA512:
-  metadata.gz: 1b1fd0486f6ca2028f1630fc0ac34e16d6a99f6be152030a14ad225c2c916dbc048f69fe8e7a83d9fc021d9c25edd4a224d2caf1e71e7124be832f83532c544e
-  data.tar.gz: 619214a39896eb66ac91d853ff622112200783d2934464b61edc57c0f045d6b128068f2dbc91b4b49fdd3a912da222bdf0eaacad311a530e8c26cfb1d5822a6c
+  metadata.gz: ba46941809fddc0f737220ff6e2f4f7fe66fef593c80ef0eb58ffed036cc9c71c4d5483abfc5fb03740537e98ad9a8c79f0b4f8d05c38bbc0f60238aedddfe87
+  data.tar.gz: 3525344cbd3da67cd91636c2cc1a796cfb98776b236c5fdf91556729bca0038de89eb9beb8bd2db00d538fc2bc050b0b8c955f25b9930fc50c49322c8642fa41

data/.rubocop.yml

@@ -3,7 +3,7 @@ plugins:
   - rubocop-rake
 
 AllCops:
-  TargetRubyVersion: 3.1
+  TargetRubyVersion: 3.3
   NewCops: enable
 
 Style/SymbolArray:

data/README.md

@@ -1,5 +1,8 @@
 # Psyllium: Makes using Ruby Fibers easier
 
+[![Gem Version](https://badge.fury.io/rb/psyllium.svg?icon=si%3Arubygems)](https://badge.fury.io/rb/psyllium)
+[![Main GH Actions workflow](https://github.com/eestrada/psyllium/actions/workflows/main.yml/badge.svg?branch=master)](https://github.com/eestrada/psyllium/actions/workflows/main.yml?query=branch%3Amaster)
+
 > Psyllium \| SIL-ee-um \|
 >
 > 1. _Dietary_ the seed of a fleawort (especially Plantago psyllium). Mainly
@@ -9,55 +12,53 @@
 
 ## What is Psyllium?
 
-Psyllium is a library to make it easier to use Ruby Fibers for everyday
-programming.
+Psyllium is a library to make it easier to use auto-scheduled Ruby Fibers,
+block on their execution, and retrieve their final values.
 
-Ruby version 3 introduced the Fiber Scheduler interface, which makes it easier
-to use Fibers for concurrent programming. However, native Thread objects still
+Ruby 3.0 introduced the Fiber Scheduler interface, making 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.
+By default, the Fiber interface centers around two types of usage:
 
-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?`.
+1. (Before Ruby 3) Explicitly and manually manipulated using `Fiber.yield`,
+   `resume`, and `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.
+Psyllium adds many of the methods of the Thread class to the builtin Fiber
+class, including `start`, `join`, and `value`. This makes 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.
 
-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.
+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.
 
-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.
+## When to use Psyllium?
 
 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?
+those Threads spend most (or all) of their time waiting on IO, then consider
+using Psyllium enhanced Fibers instead of Threads.
+
+Let's imagine a scenario where Psyllium (or Fibers generally) could be useful:
+
+- You have 100 URLs that you need to retrieve values from. Each URL has 1
+  second of network latency. Here are some solutions with memory and speed
+  tradeoffs:
+  - Solution 1: synchronously and serially retrieve values in a loop. You
+    receive all 100 responses in 100 seconds using no additional memory.
+  - Solution 2: use a thread pool of 10 threads. You receive all 100 responses
+    in 10 seconds using 10MB of additional memory (~1MB additional memory per
+    Thread).
+  - Solution 3: use one thread per URL. You receive all 100 responses in 1
+    second using 100MB of additional memory (~1MB additional memory per Thread).
+  - Solution 4: use one auto-fiber per URL. You receive all 100 responses in 1
+    second using 1.3MB of additional memory ([~13KB of physical memory
+    per Fiber](https://bugs.ruby-lang.org/issues/15997)).
+
+## When _not_ to use Psyllium?
 
 Circumstances where you shouldn't use Psyllium (or Fibers generally):
 
@@ -90,10 +91,13 @@ thread2 = Thread.start { long_running_io_operation_with_result2() }
 thread1.join
 thread2.join
 
+puts 'thread1 ended with an exception' if thread1.status.nil?
+puts 'thread2 ended without an exception' if thread2.status == false
+
 # `value` implicitly calls `join`, so the explicit `join` calls above are
 # not strictly necessary.
-value1 = thread1.value
-value2 = thread2.value
+result1 = thread1.value
+result2 = thread2.value
 ```
 
 You can now do this:
@@ -111,10 +115,13 @@ fiber2 = Fiber.start { long_running_io_operation_with_result2() }
 fiber1.join
 fiber2.join
 
+puts 'fiber1 ended with an exception' if fiber1.status.nil?
+puts 'fiber2 ended without an exception' if fiber2.status == false
+
 # `value` implicitly calls `join`, so the explicit `join` calls above are
 # not strictly necessary.
-value1 = fiber1.value
-value2 = fiber2.value
+result1 = fiber1.value
+result2 = fiber2.value
 ```
 
 ## Development

data/lib/psyllium/fiber.rb

@@ -3,8 +3,11 @@
 require 'timeout'
 
 module Psyllium
+  # Base Exception class for module code.
+  class Error < FiberError; end
+
   # Wrap Exception instances for propagation
-  class ExceptionalCompletionError < FiberError
+  class ExceptionalCompletionError < Error
     def initialize(expt)
       @internal_exception = expt
       super(@internal_exception)
@@ -59,7 +62,7 @@ module Psyllium
 
     def state_get(fiber: Fiber.current, create_missing: false)
       # Psyllium state is a thread local variable because Fibers cannot (yet)
-      # migrates across threads anyway.
+      # migrate 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.
@@ -125,11 +128,11 @@ module Psyllium
     # `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
+      raise Error.new('Cannot join self') if eql?(::Fiber.current)
+      raise Error.new('Cannot join when calling Fiber is blocking') if ::Fiber.current.blocking?
+      raise Error.new('Cannot join when called Fiber is blocking') if blocking?
+      raise Error.new('Cannot join without Fiber scheduler set') unless ::Fiber.scheduler
+      raise Error.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
@@ -149,41 +152,13 @@ module Psyllium
       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
+  # Thread has the same aliases
+  alias terminate kill
+  alias exit kill
 end

data/lib/psyllium/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: psyllium
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Ethan Estrada
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-03-12 00:00:00.000000000 Z
+date: 2025-03-25 00:00:00.000000000 Z
 dependencies: []
 description:
 email:
@@ -42,7 +42,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.1.0
+      version: 3.3.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="