callback-collection 0.1.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 78150ace9b1f03ae373409b70582aab42fded3b8ca7cf7268c9e15fcc8eba8a6
-  data.tar.gz: 98fa5ae6f33bc0116f4510d58f698c5e493fd17582843f6b067888d9cf5d82db
+  metadata.gz: 7b15736a4210e0b8985c8978498bfcde00f3d7c574626e2b51a61d65cf5f85ef
+  data.tar.gz: 51e8e8b26a322261f77fb27e0a5c23bd35cced8347da6ac6b0bc806079b40e6b
 SHA512:
-  metadata.gz: 9473879ba7b4f83ce62116855eff9b7dac6ea4923ed4cd43610490be669792bea01ed6ec273c8de58351b127a33efd36ecf0670da0a681d6116d6ebbc6fa9db4
-  data.tar.gz: f4decc447ab5a9b79a6531fdaf40d0cadec9ecfca4f0f460d85ac8c629df1ae7f4d39aaa83b8bf23f822a7d7558133a4ac99cfb278bbe8364e4a6b2aa348bf4d
+  metadata.gz: 52cacd005d07848b64da529f35c3dfbcaef61c0851e2384e453e9e6f09e9de22eacc1a478f528941f8a0a8abd66f1df7792d22449e18c66beed3e24f9fe7bc49
+  data.tar.gz: 2fba1f3f416d764d261dc0fff5f516521898b9ee8af4242079ffecad87057d8ac8ab9d67a44770f7fd84c98de3a941264de02eaffda7028adbcaddb6971a6bf5

data/README.md

@@ -6,74 +6,146 @@
 [![Documentation Status](https://img.shields.io/badge/docs-RubyDoc.info-blue.svg)](https://www.rubydoc.info/gems/callback-collection)
 [![Downloads](https://img.shields.io/gem/dt/callback-collection.svg?style=flat)](https://rubygems.org/gems/callback-collection)
 
-Une petite gem Ruby permettant de définir une collection immuable de callbacks
-nommés.
+A small Ruby gem for defining an immutable collection of named callbacks.
+
+## Why Callback Collection?
+
+`CallbackCollection` groups callback definitions during initialization and
+exposes a single `respond_with` interface for invoking them. The registry
+becomes immutable once constructed, preventing late additions and making its
+behavior easier to test and reason about.
+
+The gem does not replace framework callbacks or start threads or Ractors
+itself. It provides an independent container that applications can use within
+their own execution model.
+
+## Architectural highlights
+
+- **Immutable after initialization:** the collection and its internal registry
+  are frozen when the configuration block completes. Callback definitions can
+  then be read concurrently by multiple threads without mutating shared
+  registry state.
+- **Optional Ractor compatibility:** on Ruby 3.0 and later, `register` stores a
+  receiver and method name instead of a closure. The collection is shareable
+  when the receiver and all the state it uses are also Ractor-shareable.
+- **Ruby 2.7 and later:** the standard API and `register` do not depend on
+  `Ractor`. Applications running Ruby 2.7 retain the immutable registry and
+  concurrent thread-read behavior.
+- **Direct lookup:** `respond_with` uses `Hash#fetch` to find a callback in one
+  operation and raises an explicit error when it does not exist.
+
+Immutability protects the registry, not automatically the code executed by its
+callbacks. A callback that accesses mutable shared state remains responsible
+for its own synchronization.
 
 ## Installation
 
-Installez la gem depuis RubyGems :
+Install the gem from RubyGems:
 
 ```sh
 gem install callback-collection
 ```
 
-Avec Bundler, ajoutez-la au `Gemfile` :
+With Bundler, add it to your `Gemfile`:
 
 ```ruby
 gem "callback-collection"
 ```
 
-## Utilisation
+## Usage
 
 ```ruby
 require "callback_collection"
 
 callbacks = CallbackCollection.new do |collection|
-  collection.success { |name| "Bienvenue, #{name} !" }
-  collection.failure { |error| "Erreur : #{error.message}" }
+  collection.success { |name| "Welcome, #{name}!" }
+  collection.failure { |error| "Error: #{error.message}" }
 end
 
 callbacks.respond_with(:success, "Ruby")
-# => "Bienvenue, Ruby !"
+# => "Welcome, Ruby!"
 ```
 
-La collection est figée à la fin de son initialisation. Toute tentative
-d'ajouter ensuite un callback lève une `FrozenError`.
+The collection is frozen at the end of initialization. Attempting to add a
+callback afterward raises `FrozenError`.
 
-## Développement
+### Ractors (Ruby 3.0 and later)
+
+Blocks retain their lexical context and therefore cannot be shared between
+Ractors. To create a shareable collection, register a shareable receiver and
+one of its methods instead:
+
+```ruby
+module Handlers
+  def self.sum(left, right)
+    left + right
+  end
+end
+
+callbacks = CallbackCollection.new do |collection|
+  collection.register(:sum, Handlers)
+end
+
+Ractor.shareable?(callbacks)
+# => true
+
+worker = Ractor.new(callbacks) do |collection|
+  collection.respond_with(:sum, 20, 22)
+end
+
+result = worker.respond_to?(:value) ? worker.value : worker.take
+result
+# => 42
+```
+
+The third argument to `register` lets you use a method name that differs from
+the callback name:
+
+```ruby
+collection.register(:total, Handlers, :sum)
+```
+
+The registered receiver and the data it uses must follow Ractor shareability
+rules. Calls to `respond_with` remain unchanged. On Ruby 2.7, the gem and
+`register` remain fully usable; only Ractor execution is unavailable. The gem
+does not create workers: the application retains control over their lifecycle
+and exchanged messages.
+
+## Development
 
 ```sh
 bundle install
 bundle exec rake
 ```
 
-La tâche par défaut exécute la suite Minitest et construit la gem dans `pkg/`.
-L'intégration continue GitHub Actions vérifie le projet avec Ruby 2.7 à 3.4,
-ainsi qu'avec la dernière version stable, Ruby 4.0.
+The default task runs the Minitest suite and builds the gem in `pkg/`. GitHub
+Actions checks the project with Ruby 2.7 through 3.4 and the latest stable
+release, Ruby 4.0.
 
-## Publication
+## Publishing
 
-La publication sur RubyGems utilise
-[Trusted Publishing](https://guides.rubygems.org/trusted-publishing/) et ne
-nécessite aucune clé API dans les secrets GitHub.
+RubyGems releases use
+[Trusted Publishing](https://guides.rubygems.org/trusted-publishing/) and do
+not require an API key in GitHub secrets.
 
-Avant la première publication, créez un *Pending Trusted Publisher* dans votre
-profil RubyGems avec les paramètres suivants :
+Before the first release, create a *Pending Trusted Publisher* in your RubyGems
+profile with these settings:
 
-- gem : `callback-collection`
-- propriétaire du dépôt : `nicolasva`
-- dépôt : `callback-collection`
-- workflow : `release.yml`
-- environnement GitHub : `release`
+- gem: `callback-collection`
+- repository owner: `nicolasva`
+- repository: `callback-collection`
+- workflow: `release.yml`
+- GitHub environment: `release`
 
-Publiez ensuite une version en poussant le tag correspondant à
-`CallbackCollection::VERSION` :
+Release a version by pushing the tag that matches
+`CallbackCollection::VERSION`:
 
 ```sh
-git tag v0.1.0
-git push origin v0.1.0
+VERSION=$(ruby -Ilib -rcallback_collection/version -e 'print CallbackCollection::VERSION')
+git tag "v${VERSION}"
+git push origin "v${VERSION}"
 ```
 
-GitHub Actions construit et publie alors la gem. RubyDoc génère
-automatiquement sa documentation, et les badges de version et de
-téléchargements deviennent actifs après la première publication.
+GitHub Actions then builds and publishes the gem. RubyDoc generates its
+documentation automatically, and the version and download badges update after
+publication.

data/lib/callback_collection/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 class CallbackCollection
-  VERSION = "0.1.0"
+  VERSION = "0.2.1"
 end

data/lib/callback_collection.rb

@@ -12,10 +12,30 @@ require_relative "callback_collection/version"
 #   callbacks.respond_with(:success, "data")
 #   # => "Received data"
 class CallbackCollection
+  class RegisteredCallback
+    def initialize(receiver, method_name)
+      @receiver = receiver
+      @method_name = method_name
+      freeze
+    end
+
+    def call(*args, **kwargs, &block)
+      return @receiver.public_send(@method_name, *args, &block) if kwargs.empty?
+
+      @receiver.public_send(@method_name, *args, **kwargs, &block)
+    end
+  end
+  private_constant :RegisteredCallback
+
   def initialize
     callbacks
     yield(self) if block_given?
     callbacks.freeze
+    freeze
+  end
+
+  def register(callback, receiver, method_name = callback)
+    store_callback(callback, RegisteredCallback.new(receiver, method_name))
   end
 
   def respond_with(callback, *args, **kwargs, &block)
@@ -30,10 +50,7 @@ class CallbackCollection
 
   def method_missing(method_name, *args, &block)
     if block
-      raise FrozenError, "Cannot define a callback after initialization." if callbacks.frozen?
-
-      callbacks[method_name] = block
-      self
+      store_callback(method_name, block)
     else
       super
     end
@@ -48,4 +65,13 @@ class CallbackCollection
   def callbacks
     @callbacks ||= {}
   end
+
+  private
+
+  def store_callback(callback, handler)
+    raise FrozenError, "Cannot define a callback after initialization." if callbacks.frozen?
+
+    callbacks[callback] = handler
+    self
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: callback-collection
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Nicolas Vandenbogaerde
@@ -56,7 +56,7 @@ homepage: https://github.com/nicolasva/callback-collection
 licenses: []
 metadata:
   rubygems_mfa_required: 'true'
-  documentation_uri: https://www.rubydoc.info/gems/callback-collection/0.1.0
+  documentation_uri: https://www.rubydoc.info/gems/callback-collection/0.2.1
   source_code_uri: https://github.com/nicolasva/callback-collection
 rdoc_options: []
 require_paths: