callback-collection 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1b8d078e3adf404673581fa27324c5047a56f553607ed5a061cfd2235beda3af
-  data.tar.gz: 46b3b5395ebe4f3b28613abe64aa0732d4e5b090cdada60680706c6552e73a1a
+  metadata.gz: 7b15736a4210e0b8985c8978498bfcde00f3d7c574626e2b51a61d65cf5f85ef
+  data.tar.gz: 51e8e8b26a322261f77fb27e0a5c23bd35cced8347da6ac6b0bc806079b40e6b
 SHA512:
-  metadata.gz: bb5f40c036768f917b0b2478fb1abfac644cc1514cb770c012503f03e3a5aea4c7f1607cd5f88ad74a9de4febad7b01096ca415c972654ff54c2febd0877ad6a
-  data.tar.gz: 3579c01beef765ea0388ee4ce0344fc89ddfbc35ecd524b9307c0536fbe14529ce77b9eee1da348c3271ed948a2649297c2f905bb37438ce27261bb0844ea81f
+  metadata.gz: 52cacd005d07848b64da529f35c3dfbcaef61c0851e2384e453e9e6f09e9de22eacc1a478f528941f8a0a8abd66f1df7792d22449e18c66beed3e24f9fe7bc49
+  data.tar.gz: 2fba1f3f416d764d261dc0fff5f516521898b9ee8af4242079ffecad87057d8ac8ab9d67a44770f7fd84c98de3a941264de02eaffda7028adbcaddb6971a6bf5

data/README.md

@@ -6,45 +6,74 @@
 [![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`.
 
-### Ractors (Ruby 3.0 et versions ultérieures)
+### Ractors (Ruby 3.0 and later)
 
-Les blocs conservent leur contexte lexical et ne peuvent donc pas être partagés
-entre Ractors. Pour créer une collection partageable, enregistrez plutôt un
-objet partageable et l'une de ses méthodes :
+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
@@ -69,46 +98,47 @@ result
 # => 42
 ```
 
-Le troisième argument de `register` permet d'utiliser un nom de méthode
-différent du nom du callback :
+The third argument to `register` lets you use a method name that differs from
+the callback name:
 
 ```ruby
 collection.register(:total, Handlers, :sum)
 ```
 
-Le receveur enregistré et les données qu'il utilise doivent eux-mêmes respecter
-les règles de partage des Ractors. L'appel à `respond_with` reste identique.
-Sous Ruby 2.7, la gem et `register` restent utilisables normalement ; seule
-l'exécution avec `Ractor` est indisponible.
+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.
 
-## Développement
+## 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
 VERSION=$(ruby -Ilib -rcallback_collection/version -e 'print CallbackCollection::VERSION')
@@ -116,6 +146,6 @@ 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.2.0"
+  VERSION = "0.2.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: callback-collection
 version: !ruby/object:Gem::Version
-  version: 0.2.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.2.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: