Skip to content

README.md

Latest commit

 

History

History
199 lines (141 loc) · 4.31 KB

README.md

File metadata and controls

199 lines (141 loc) · 4.31 KB

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.