Skip to content

Feat: The "inception pool" aka Ratomic::LocalPool - #26

Merged
kanutocd merged 4 commits into
trunkfrom
feat/the-inception-pool
Jun 10, 2026
Merged

Feat: The "inception pool" aka Ratomic::LocalPool#26
kanutocd merged 4 commits into
trunkfrom
feat/the-inception-pool

Conversation

@kanutocd

@kanutocd kanutocd commented Jun 9, 2026

Copy link
Copy Markdown
Collaborator

Summary

This PR introduces Ratomic::LocalPool, a new pooling primitive for resources that should remain local to the Ractor that created them.

Examples include:

  • Redis clients
  • PostgreSQL connections
  • HTTP clients
  • Kafka producers
  • Other stateful resources with internal connection/socket/native state

Background

While experimenting with Redis clients under Ruby Ractors, the ownership-transfer semantics were exposed that they are not always appropriate for live resources.

Ratomic::Pool correctly implements ownership transfer:

Pool  -> Caller -> Pool

However, Redis clients contain internal state that cannot safely participate in ownership transfer after initialization. This resulted in failures such as:

Ractor::MovedError

Several approaches were explored, including pool reset behavior, but the underlying issue was resource ownership rather than resource cleanup.

Solution

Introduce Ratomic::LocalPool.

Instead of moving live resources between Ractors, the facade remains shareable while each Ractor lazily creates and owns its own local resource pool.

Architecture:

LocalPool facade 
       ↓
Ractor-local pool
       ↓
Live resources

Calling this the "Inception Pool" design:

Pool
  ↓
Pool
  ↓
Resource

A Pool within a Pool :)

Validation

Added Redis smoke tests covering:

basic_redis.rb

  • Thread execution
  • Ractor execution
  • Shared facade usage

queue_redis.rb

  • Multiple producers
  • Multiple consumers
  • Queue draining verification

Observed results:

  • No Ractor::MovedError
  • No Ractor::IsolationError
  • Successful queue drain
  • Successful operation from both Threads and Ractors

kanutocd added 4 commits June 10, 2026 02:35
Add Ratomic::LocalPool, a shareable facade over per-Ractor local
resource pools.

Designed for live resources such as Redis clients and database
connections where ownership preservation is preferable to ownership
transfer.

Includes Redis smoke tests and documentation updates.
@kanutocd
kanutocd requested a review from mperham June 9, 2026 19:26
@kanutocd
kanutocd merged commit 1c569fa into trunk Jun 10, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant