Function

Summary

Creates a "ring" object.

Package

hcl

Signature

make-ring size name &optional delete-function => ring

Arguments

size

A positive fixnum.

name

A string.

delete-function

A function designator for a function of one argument.

Values

ring

A "ring" object.

Description

The function make-ring creates a "ring" object, which can hold up to size elements. A ring has stack like behavior but is limited in size, and can be rotated.

size is the maximum number of elements that the ring ring can hold. Once ring has this number of elements, if an element is added to ring (by ring-push), an element is first removed from the ring.

name simply names the ring, but has no effect on its functionality. It is used when printing the ring object, and is returned by ring-name.

delete-function, if supplied, is called each time an element is removed from the ring (by ring-push) because it is full. The default value of delete-function is #'identity.

The ring keeps the elements in a logical ring with an "insertion position". The function ring-push adds an element before the insertion position. If the ring is full, it first removes the element immediately after the insertion position.

The function ring-pop removes from the ring the element before the insertion point, and returns that element. Thus when using ring-push and ring-pop on their own, the ring behaves like a stack with limited length.

rotate-ring can be used to move the insertion point. ring-ref can be used to index into the ring. map-ring, position-in-ring, and position-in-ring-forward can be used to iterate through the ring's elements.

All access to a ring is thread-safe. Therefore access to a ring may hang if another process keeps it locked. If you need to guarantee no hanging, you can use with-ring-locked with non-nil timeout around the critical calls.

See also

ring-push
ring-pop
rotate-ring
ring-ref
ring-length
ringp
ring-name
map-ring
position-in-ring
with-ring-locked