Class: RactorQueue

Inherits:
Object
  • Object
show all
Includes:
Interface
Defined in:
lib/ractor_queue/errors.rb,
lib/ractor_queue/version.rb,
lib/ractor_queue/interface.rb,
lib/ractor_queue/ractor_queue.rb

Defined Under Namespace

Modules: Interface Classes: Error, NotShareableError, TimeoutError

Constant Summary collapse

VERSION = 
"0.2.0"
EMPTY =

Public sentinel returned by try_pop when the queue is empty. Use equal? (identity) to check — never == — so that nil is an unambiguous payload.

entry = q.try_pop
return if entry.equal?(RactorQueue::EMPTY)

EMPTY_SENTINEL

Class Method Summary collapse

Methods included from Interface

#async_pop, #async_push, #empty?, #full?, #pop, #push, #size, #try_pop, #try_push

Class Method Details

.new(capacity:, validate_shareable: false) ⇒ Object

Parameters:

  • capacity (Integer) —

    Maximum number of elements the queue can hold.

  • validate_shareable (Boolean) (defaults to: false) —

    Raise NotShareableError on non-shareable pushes.



14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
 
# File 'lib/ractor_queue/ractor_queue.rb', line 14

def self.new(capacity:, validate_shareable: false)
  instance = super(capacity)
  # RGENGC write-barrier fix: mark the queue as WB-unprotected so minor GC
  # always scans gc_slots_ and keeps queued young objects alive.
  # Without this, pushing a young VALUE into an OLD StandardQueue creates an
  # untracked old→young reference — minor GC never marks it, the VALUE is
  # collected, and subsequent pops return garbage (crash at scale).
  # We pass `instance` explicitly because rb_gc_writebarrier_unprotect needs
  # the raw Ruby VALUE; there is no way to capture `self` as a VALUE inside
  # a Rice member-function binding without an explicit argument.
  instance._gc_unprotect(instance)
  instance.instance_variable_set(:@validate_shareable, validate_shareable)
  # Make the queue instance itself Ractor-shareable. This deep-freezes the Ruby
  # wrapper object. The C++ AtomicQueueB2 buffer is not affected by Ruby's freeze.
  Ractor.make_shareable(instance)
  instance
end