ractor-wrapper 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9fec3af2b1b8b9c105260fe2fca50d69e48de205dd2dd791592317ee41286af3
-  data.tar.gz: e7b4487502427ec05f3dc530925e9efecd8d599e75f4dc2b82c7371592986f59
+  metadata.gz: b3948e5f98b34503dc8e6075eb8a186ae1c76a53f0f45164396bb006ad802964
+  data.tar.gz: 58eaa1ac8d9d0088b1f8df5e45d746a084a921eef53eb96563c0700eb9144dde
 SHA512:
-  metadata.gz: 0ab154c16e2ed53f65a042bf18b85448cb0115e6b1616db5cce96084767ae1f00c23392ba48560177f34c43d757b59e282c05891702af927f40f72fe989b33e1
-  data.tar.gz: 8e16f5694e46c571deac8d66f56bb23467572bad838038d941955f2edaca76537ef741df79b63da0bc28c31708a31ac3ba699e3a2a661b56552dc6b1050625a0
+  metadata.gz: 3b31f168446571aad39874d04542818ccea56bb3165e2a081fb5135f72b0498c2e73eb5fec4431cd712f8326ced6c6924a3600833895e356fb7cb154ac6f2023
+  data.tar.gz: 9d679b50a36ee4303117d46bd404f649ca1a71f724c8dbe6ba13ba28f77228e1071839d7b06d8c965cb7946e411178b86bcfb08b77c0bfdc2e0c2420121ede1a

data/CHANGELOG.md

@@ -1,5 +1,36 @@
 # Release History
 
+### v0.4.0 / 2026-03-30
+
+This release includes two major changes: it greatly improves robustness in the case of server crashes, and it reworks the method call configuration interface. This involves several breaking changes, and I expect the interface will continue to be a bit unstable for now as I'm working through use cases and edge cases. The README has also been expanded to include more information on the configuration options and the known issues.
+
+* ADDED: Uses a separate `Ractor::Wrapper::Configuration` class for block-based initialization. Removed the configuration mutation methods from `Ractor::Wrapper` itself.
+* BREAKING CHANGE: The method configuration interface now uses symbolic settings values instead of booleans for more flexibility
+* ADDED: Support for suppressing return values for methods and blocks that unintentionally return something they shouldn't
+* BREAKING CHANGE: Raises `Ractor::Wrapper::StoppedError` instead of `Ractor::ClosedError` if a method is called via the wrapper after the wrapper has stopped
+* BREAKING CHANGE: `Wrapper#join` now returns normally rather than raising, if an isolated wrapper terminated due to a crash
+* BREAKING FIX: `Wrapper#join` no longer hangs if a local wrapper crashes, but returns to indicate that the wrapper has stopped (albeit non-normally)
+* FIXED: Internal cleanup is more robust if a crash occurs in the wrapper
+* FIXED: Method calls raise `Ractor::Wrapper::CrashedError` instead of hanging if the wrapper crashes during handling
+* FIXED: Prevented port leaks if a method call send or a block yield send fails
+* FIXED: Methods that return or yield self return/yield the stub instead
+* FIXED: The `recover_object` method now raises `Ractor::Wrapper::Error` if recovery failed
+* DOCS: Updates to README
+
+### v0.3.0 / 2026-01-05
+
+This is a major update, and the library, while still experimental, is finally somewhat usable. The examples in the README now actually work!
+
+Earlier versions were severely hampered by limitations of the Ractor implementation in Ruby 3. Many of these were fixed in Ruby 4.0, and Ractor::Wrapper has been updated to take advantage of it. This new version requires Ruby 4.0.0 or later, and includes a number of enhancements:
+
+* Support for running a wrapper in the current Ractor, useful for wrapping objects that cannot be moved, or that must run in the main Ractor. (By default, wrapped objects are still moved into an isolated Ractor to maximize cleanliness and concurrency.)
+* Support for running a wrapper sequentially without worker threads. This is now the default behavior, which does not spawn any extra threads in the wrapper. (Earlier behavior would spawn exactly one worker thread by default.)
+* Limited support for passing blocks to a wrapped object. You can cause a block to run "in place" within the wrapper, as long as the block can be made shareable (i.e. does not access any outside data), or have the block run in the caller's context with the cost of some additional communication. You can also configure that communication to move or copy data.
+* Provided Ractor::Wrapper#join for waiting for a wrapper to complete without asking for the wrapped object back.
+* Some of the configuration parameters have been renamed.
+
+Some caveats remain, so please consult the README for details. This library should still be considered experimental, and not suitable for production use. I reserve the right to make breaking changes at any time.
+
 ### v0.2.0 / 2021-03-08
 
 * BREAKING CHANGE: The wrapper now copies (instead of moves) arguments and return values by default.

data/CLAUDE.md

@@ -0,0 +1,76 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Commands
+
+This project uses [Toys](https://dazuma.github.io/toys) for task management (not Rake).
+
+```bash
+# Run full CI pipeline
+toys ci
+
+# Run individual components
+toys test      # Tests only
+toys rubocop   # Linting and code style only
+toys yardoc    # Documentation only
+toys build     # Build gem only
+
+# Run a single test file
+toys test test/test_wrapper.rb
+```
+
+## Architecture
+
+The entire library lives in `lib/ractor/wrapper.rb`. The public entry point is `Ractor::Wrapper`, which wraps a non-shareable object and exposes it to other Ractors via a shareable `Stub` proxy.
+
+### Core classes
+
+- **`Ractor::Wrapper`** — Public API. Wraps an object and manages its lifecycle. Accepts options like `use_current_ractor:`, `threads:`, `name:`, and per-method settings via `configure_method`.
+- **`Ractor::Wrapper::Stub`** — Frozen, shareable proxy passed to other Ractors. Uses `method_missing` to forward calls back to the wrapper via message passing.
+- **`Ractor::Wrapper::MethodSettings`** — Frozen configuration controlling copy vs. move semantics for arguments and return values, and block handling behavior.
+- **`Ractor::Wrapper::Server`** — Private backend. Receives `CallMessage` objects and dispatches them to the wrapped object, then returns results via `ReturnMessage`, `ExceptionMessage`, or `YieldMessage`.
+
+### Two execution modes
+
+1. **Isolated mode** (default) — the wrapped object is moved into a new Ractor. Other Ractors interact with it through the Stub. After `join`, the object can be recovered via `recover_object`.
+2. **Local mode** (`use_current_ractor: true`) — the server runs as Thread(s) inside the current Ractor. The object is never moved. Used for objects that cannot be transferred between Ractors (e.g., SQLite3 connections).
+
+### Concurrency within the server
+
+- **Sequential** (default) — one call at a time, no worker threads.
+- **Concurrent** — multiple worker threads (set via `threads:`), for thread-safe wrapped objects.
+
+### Message protocol
+
+All inter-Ractor communication uses frozen message structs defined in the file: `CallMessage`, `ReturnMessage`, `ExceptionMessage`, `YieldMessage`, `StopMessage`, `JoinMessage`, `WorkerStoppedMessage`. Block calls round-trip: the server sends a `YieldMessage` to the caller Ractor, the caller executes the block and sends back a result or exception.
+
+### Lifecycle
+
+1. Wrapper starts → Server enters **running** phase (accepts calls).
+2. `async_stop` or `stop` called → Server enters **stopping** phase (rejects new calls, drains workers).
+3. All workers finish → Server enters **cleanup** phase and shuts down.
+4. `join` returns → In isolated mode, `recover_object` retrieves the wrapped object.
+
+## Code Style
+
+- Ruby 4.0+ target
+- Double-quoted strings (`Style/StringLiterals: double_quotes`)
+- Trailing commas in multiline arrays and hashes
+- Bracket-style symbol and word arrays (`[:foo, :bar]` not `%i[foo bar]`)
+- Max line length: 120
+- `Style/DocumentationMethod: Enabled` — public methods require YARD docs
+- Tests use Minitest spec style with assertions (not expectations)
+- Top-level constants must be prefixed with `::` (e.g. `::File`, `::Regexp`, `::Gem::Version`) to avoid ambiguous resolution within nested namespaces. Relative constants defined within the current namespace should not be prefixed. Note that Kernel method calls such as `Array(x)`, `Integer(x)`, `Float(x)` look like constants but are not and do not get the prefix.
+
+## Testing
+
+- Minitest spec style: `describe`/`it` blocks with `assert_*` assertions (not expectations)
+- Test files follow the `test_*.rb` naming convention
+
+## General coding instructions
+
+- Unless instructed otherwise, always use red-green test-driven development when making code changes. For each step in a coding task, first write tests and confirm they fail. Then write code to make the tests pass.
+- Unless instructed otherwise, always git commit after a step is complete and the tests pass.
+- Conventional Commits format required (`fix:`, `feat:`, `docs:`, etc.)
+- Prefer Ruby for any one-off scripts you need to write as part of your work.

data/LICENSE.md

@@ -1,6 +1,6 @@
 # License
 
-Copyright 2021 Daniel Azuma
+Copyright 2021-2026 Daniel Azuma
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal