The earlier posts seem to be missing the point of a ring buffer. They require no locks when they have one writer thread and one reader thread. Using push+shift produces a queue, but not specifically a ring buffer.

For example, the keyboard buffer used to be a ring buffer. The keyboard would place messages into it to be read by the system.

What the OP is missing is that ring buffers are usually implemented using ever growing indexes into an array, mod the size of the buffer. If you don't want to limit the size of the buffer, you can use a linked list instead of an array. Hashes don't figure into the equation.

my $head = 0;  # Can only be modified by the lone writer thread
my $tail = 0;  # Can only be modified by the lone reader thread
my $size = 4;  # Can hold one less than $size
my @buf = (undef) x $size;

# Can only be called by the lone reader thread
sub is_empty {
    return $tail == $head;
}

# Can only be called by the lone reader thread
sub dequeue {
    return () if is_empty();
    my $val = $buf[$tail];
    $tail = ( $tail + 1 ) % @buf;
    return $val;
}

# Can only be called by the lone writer thread
sub is_full {
    return ($head + 1) % @buf == $tail;
}

# Can only be called by the lone writer thread
sub enqueue {
    my ($val) = @_;
    return 0 if is_full();
    $buf[$head] = $val;
    $head = ( $head + 1 ) % @buf;
    return 1;
}
[download]

If you have more than one writer thread or more than one reader thread, locking is necessary.

Now, if you want to have multiple buffers going, you can use an object.

package Data::RingBuffer;

sub new {
    my ($class, $size) = @_;
    return bless({
        head => 0,
        tail => 0,
        buf  => [ (undef) x $size ],
    }, $class);
}

sub is_empty {
    my ($self) = @_;
    return $self->{tail} == $self->{head};
}

sub dequeue {
    my ($self) = @_;
    my $buf = $self->{buf};
    return () if $self->is_empty();
    my $val = $buf->[$self->{tail}];
    $self->{tail} = ( $self->{tail} + 1 ) % @$buf;
    return $val;
}

sub is_full {
    my ($self) = @_;
    my $buf = $self->{buf};
    return ($self->{head} + 1) % @$buf == $self->{tail};
}

sub enqueue {
    my ($self, $val) = @_;
    my $buf = $self->{buf};
    return 0 if $self->is_full();
    $buf->[$self->{head}] = $val;
    $self->{head} = ( $self->{head} + 1 ) % @$buf;
    return 1;
}
[download]

Update: Fixed typos in code. Simplified code.

Ring buffers are used in performance critical situations, often in embedded code, where a fixed size chunk of memory is allocated and used as a queue for buffering data.

The usual implementation uses two pointers (indexes). Details vary a little, but by inspecting the pointers you can determine if the buffer is full (incrementing the input pointer would make it match the output pointer), empty (input pointer matches output pointer) or somewhere between. Very often the buffer size is a power of 2 to take advantage binary arithmetic operations to reduce code complexity and increase speed.

Except as an exercise there is no application I can think of where writing a ring buffer in Perl would be useful. The following may be of interest though:

use strict;
use warnings;

my $buffer = new ();

print "Buffer has ", $buffer->count (), " values\n";
$buffer->push ($_) for 1 .. 200;
print "Buffer has ", $buffer->count (), " values\n";
$buffer->pop () for 1 .. 100;
print "Buffer has ", $buffer->count (), " values\n";
$buffer->push ($_ + 200) for 1 .. 150;
print "Buffer has ", $buffer->count (), " values\n";


sub new {
    my @bufferArray;
    my $buffSize = 256;
    
    $#bufferArray = 256; # set buffer size
    return $buffer = bless {
        buffer => \@bufferArray,
        in => 0,
        out => 0,
        buffSize => $buffSize,
        };
}


sub count {
    my ($self) = @_;
    my $used = $self->{in} - $self->{out};
    
    $used += $self->{buffSize} if $used < 0;
    return $used;
}


sub pop {
    my ($self) = @_;
    
    die "Buffer underflow" if $self->{in} == $self->{out};
    
    my $value = $self->{buffer}[$self->{out}];
    $self->{out} = ($self->{out} + 1) % $self->{buffSize};
    return $value;
}


sub push {
    my ($self, $value) = @_;
    
    die "Buffer overflow" if $self->count () + 1 == $self->{buffSize};
    $self->{buffer}[$self->{in}] = $value;
    $self->{in} = ($self->{in} + 1) % $self->{buffSize};
}
[download]

Prints:

Buffer has 0 values
Buffer has 200 values
Buffer has 100 values
Buffer has 250 values
[download]

Update: Fixed reporting error in push - thanks ikegami!

The comments that note that arrays manage themselves in Perl are certainly true, it's that, if I'm interpreting your question correctly, you want to learn about traditional data structure management.

So - you have then empty condition correct: if the head and tail point to the same node, the buffer is empty. A clearer statement of the "full" state is "If the next of the tail node points to the head, then the buffer is full".

First: setting up a ring buffer programatically rather than declaratively. You want an array (fixed size) of hashes, each one "pointing" to the next except for the last, which should point to the first. So let's do that:

my @ring;
use constant RING_SIZE => 10;
for my $buffer_pointer (0..RING_SIZE) {
  my $next_element = ($buffer_pointer + 1) % RING_SIZE;
  $ring[$buffer_pointer] = { data =>'', next => $next_element };
}
[download]

1. You have one thread or process reading a buffer, and a second one writing it.
2. You are memory-constrained and can only afford to devote a controlled, relatively small amount of storage to the process
3. You want relatively fast response time from both processes.

You do, as others have also mentioned, need a lock to serialize access to the buffer, since the operations to manage the buffer are not atomic - it takes more than one step to decide that there's something in it (or room available) and then alter the buffer accordingly. If you were really planning on implementing this for some reason (a pool of reusable database handles?), you'd need the locking. And they're also right that implementing the put/get management with shift and push would probably be far more efficient and easier to debug.

Can't you just use "push" and "shift"? Why the big complication with "circular ring buffers"?

What are you're doing doesn't look good for me. You can do the same much simpler:

my @buffer;

sub store {
    return "Buffer is full" if @buffer >= 4;
    push @buffer, $_[0];
}

sub retrieve {
    shift @buffer;
}
[download]

Update: ikegami is right, if you have reader and writer threads ring buffer is quite useful. And my code would require some synchronization.