The Queue class implements multi-producer, multi-consumer queues. It is especially useful in threaded programming when information must be exchanged safely between multiple threads. The Queue class implements all the required locking semantics.

The class implements FIFO type of queue. In a FIFO queue, the first tasks added are the first retrieved.

Example:

require 'thread'
queue = Queue.new

producer = Thread.new do
  5.times do |i|
     sleep rand(i) # simulate expense
     queue << i
     puts "#{i} produced"
  end
end

consumer = Thread.new do
  5.times do |i|
     value = queue.pop
     sleep rand(i/2) # simulate expense
     puts "consumed #{value}"
  end
end
Methods
#
C
D
E
L
N
P
S
Class Public methods
new()

Creates a new queue instance.

static VALUE
rb_queue_initialize(VALUE self)
{
    RSTRUCT_SET(self, QUEUE_QUE, ary_buf_new());
    RSTRUCT_SET(self, QUEUE_WAITERS, ary_buf_new());
    return self;
}
Instance Public methods
<<(p1)
Alias for: push
clear()

Removes all objects from the queue.

static VALUE
rb_queue_clear(VALUE self)
{
    rb_ary_clear(GET_QUEUE_QUE(self));
    return self;
}
close

Closes the queue. A closed queue cannot be re-opened.

After the call to close completes, the following are true:

  • closed? will return true

  • close will be ignored.

  • calling enq/push/<< will return nil.

  • when empty? is false, calling deq/pop/shift will return an object from the queue as usual.

ClosedQueueError is inherited from StopIteration, so that you can break loop block.

Example:

    q = Queue.new
    Thread.new{
      while e = q.deq # wait for nil to break loop
        # ...
      end
    }
    q.close
static VALUE
rb_queue_close(VALUE self)
{
    return queue_do_close(self, FALSE);
}
closed?

Returns true if the queue is closed.

static VALUE
rb_queue_closed_p(VALUE self)
{
    return queue_closed_p(self) ? Qtrue : Qfalse;
}
deq(*args)
Alias for: pop
empty?

Returns true if the queue is empty.

static VALUE
rb_queue_empty_p(VALUE self)
{
    return queue_length(self) == 0 ? Qtrue : Qfalse;
}
enq(p1)
Alias for: push
length
size

Returns the length of the queue.

Also aliased as: size
static VALUE
rb_queue_length(VALUE self)
{
    unsigned long len = queue_length(self);
    return ULONG2NUM(len);
}
num_waiting()

Returns the number of threads waiting on the queue.

static VALUE
rb_queue_num_waiting(VALUE self)
{
    unsigned long len = queue_num_waiting(self);
    return ULONG2NUM(len);
}
pop(non_block=false)
deq(non_block=false)
shift(non_block=false)

Retrieves data from the queue.

If the queue is empty, the calling thread is suspended until data is pushed onto the queue. If non_block is true, the thread isn't suspended, and ThreadError is raised.

Also aliased as: deq, shift
static VALUE
rb_queue_pop(int argc, VALUE *argv, VALUE self)
{
    int should_block = queue_pop_should_block(argc, argv);
    return queue_do_pop(self, should_block);
}
push(object)
enq(object)
<<(object)

Pushes the given object to the queue.

Also aliased as: enq, <<
static VALUE
rb_queue_push(VALUE self, VALUE obj)
{
    return queue_do_push(self, obj);
}
shift(*args)
Alias for: pop
size()
Alias for: length