solid-queue-jruby

JRuby compatibility layer for Solid Queue.

The Problem

Solid Queue uses fork() for worker processes, which doesn't work on JRuby.

The Solution

This gem replaces fork-based workers with thread-based workers on JRuby, while maintaining the same API and behavior. Zero configuration required.

Installation

Add to your Gemfile:

gem 'solid_queue'
gem 'solid-queue-jruby', platform: :jruby

Or install directly:

gem install solid-queue-jruby

Usage

Just require it. That's it.

require 'solid_queue'
require 'solid-queue-jruby'

# Everything works exactly the same
SolidQueue.start

How It Works

On JRuby, this gem:

1. Detects the JRuby runtime automatically
2. Replaces fork-based spawning with thread-based spawning
3. Maintains the same Solid Queue API
4. Provides thread-local worker state for observability

On MRI/CRuby, it does nothing (fork works fine there).

Features

• Zero configuration - just works
• Drop-in compatibility with Solid Queue
• Thread-based execution (leverages JRuby's real parallelism)
• Same API as fork-based workers
• Thread-local state for observability
• Graceful shutdown support

Runtime Detection

# Check if running on JRuby
SolidQueue::JRuby::Runtime.jruby?
# => true

# Get runtime info
SolidQueue::JRuby.info
# => {
#   ruby_engine: "jruby",
#   ruby_version: "3.1.0",
#   jruby_version: "9.4.0.0",
#   executor: :thread,
#   compatible: true,
#   solid_queue_version: "0.1.0"
# }

Architecture

This gem uses runtime detection to choose the best execution strategy:

case RUBY_ENGINE
when 'jruby'   then :thread  # This gem's contribution
when 'ruby'    then :fork    # Solid Queue default
else                :spawn   # Fallback
end

Why Thread-Based on JRuby?

JRuby runs on the JVM, which provides:

• True parallelism (no GVL)
• Efficient threading (native JVM threads)
• Better resource sharing (same heap)

Making threads the ideal choice for JRuby workers.

Observability

Thread-based workers maintain state for monitoring:

# Get worker stats (if you have access to supervisor)
supervisor.worker_stats
# => [{
#   worker_id: "jruby-worker-12345",
#   status: "running",
#   jobs_processed: 42,
#   uptime_seconds: 3600,
#   alive: true
# }]

Comparison: Fork vs Thread

Feature	Fork (MRI)	Thread (JRuby)
Parallelism	Process-level	True threads (no GVL)
Memory	Separate	Shared heap
Startup	Slower	Faster
OS Support	Unix only	Cross-platform
Observability	OS tools (ps, top)	Application-level

Requirements

• Ruby >= 2.7
• JRuby >= 9.3 (for best performance)
• Solid Queue >= 0.1.0

Performance

This gem provides significant performance improvements on JRuby:

• 3.96x speedup on 4-core CPU (99% parallel efficiency!)
• 383 jobs/second throughput
• 33x faster worker spawning vs fork()
• Lower memory usage (shared heap vs copy-on-write)

See BENCHMARKS.md for detailed performance analysis.

Run Benchmarks

jruby benchmark.rb

Automatically displays your system specs and performance metrics.

Development

# Clone the repo
git clone https://github.com/CufeHaco/solid-queue-jruby
cd solid-queue-jruby

# Install dependencies
bundle install

# Run professional test suite (recommended)
jruby test_suite.rb

# Run unit tests
jruby -S rake test

# Run benchmarks
jruby benchmark.rb

See TESTING.md for all available test scripts.

Test Results

The professional test suite runs 29 comprehensive tests on JRuby:

• ✓ Runtime detection and compatibility
• ✓ Component loading
• ✓ Thread executor functionality
• ✓ Rails/Solid Queue integration
• ✓ System information detection
• ✓ Performance validation

jruby test_suite.rb
# => 29 tests, 100% pass rate

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/CufeHaco/solid-queue-jruby.

License

MIT License. See LICENSE.txt.

Credits

• Built by Troy Mallory
• Inspired by discussions with @headius and the JRuby community
• Ayo'Cate Fenv (Red Eagle Crossing) Team. Lower Muskogee Creek Tribe East of the Mississippi.