Module: RactorQueue::Interface

Included in:
RactorQueue
Defined in:
lib/ractor_queue/interface.rb

Instance Method Summary collapse

Instance Method Details

#async_pop(timeout: nil) ⇒ Object

Fiber-scheduler-aware pop. Yields to the async reactor on every empty check via sleep(0) rather than spinning with Thread.pass first. Use inside Async { } blocks. Degrades gracefully to a near-no-op sleep in plain Thread context (no scheduler installed). Raises RactorQueue::TimeoutError if timeout expires.



42
43
44
45
46
47
48
49
50
 
# File 'lib/ractor_queue/interface.rb', line 42

def async_pop(timeout: nil)
  deadline = timeout ? Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout : nil
  loop do
    result = c_try_pop
    return result unless result.equal?(EMPTY_SENTINEL)
    raise TimeoutError if deadline && Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
    sleep(0)
  end
end

#async_push(obj, timeout: nil) ⇒ Object

Fiber-scheduler-aware push. Yields to the async reactor on every full check via sleep(0) rather than spinning with Thread.pass first. Use inside Async { } blocks. Degrades gracefully in plain Thread context. Raises RactorQueue::TimeoutError if timeout expires.



56
57
58
59
60
61
62
63
64
 
# File 'lib/ractor_queue/interface.rb', line 56

def async_push(obj, timeout: nil)
  validate_shareable!(obj) if @validate_shareable
  deadline = timeout ? Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout : nil
  loop do
    return self if c_try_push(obj)
    raise TimeoutError if deadline && Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
    sleep(0)
  end
end

#empty? ⇒ Boolean

True if queue appears empty (approximate).

Returns:

  • (Boolean) 


70
 
# File 'lib/ractor_queue/interface.rb', line 70

def empty?  = was_empty

#full? ⇒ Boolean

True if queue appears full (approximate).

Returns:

  • (Boolean) 


73
 
# File 'lib/ractor_queue/interface.rb', line 73

def full?   = was_full

#pop(timeout: nil) ⇒ Object

Blocking pop. Spins until an element is available. Returns the object. Raises RactorQueue::TimeoutError if timeout expires.



33
34
35
 
# File 'lib/ractor_queue/interface.rb', line 33

def pop(timeout: nil)
  blocking_pop(timeout)
end

#push(obj, timeout: nil) ⇒ Object

Blocking push. Spins until space is available. Returns self. Raises RactorQueue::TimeoutError if timeout expires. Ruby interrupt-aware via Thread.pass between retries.



26
27
28
29
 
# File 'lib/ractor_queue/interface.rb', line 26

def push(obj, timeout: nil)
  validate_shareable!(obj) if @validate_shareable
  blocking_push(obj, timeout)
end

#size ⇒ Object

Approximate current element count.



67
 
# File 'lib/ractor_queue/interface.rb', line 67

def size    = was_size

#try_pop ⇒ Object

Non-blocking pop. Returns the object, or RactorQueue::EMPTY if the queue is empty. EMPTY is a unique frozen sentinel distinct from nil, so nil is an unambiguous payload value.

entry = q.try_pop
if entry.equal?(RactorQueue::EMPTY)
  # queue was empty
else
  process(entry)   # entry may be nil if nil was pushed
end



19
20
21
 
# File 'lib/ractor_queue/interface.rb', line 19

def try_pop
  c_try_pop
end

#try_push(obj) ⇒ Object

Non-blocking push. Returns true if enqueued, false if full.



4
5
6
7
 
# File 'lib/ractor_queue/interface.rb', line 4

def try_push(obj)
  validate_shareable!(obj) if @validate_shareable
  c_try_push(obj)
end