README
¶
tape
Documentation
¶
Overview ¶
Package tape implements a file-based FIFO queue.
The typical use case is to use an os.File as backing storage and has special handling for this use case. However, any type that implements io.ReaderAt and io.WriterAt can be used. The documentation is written with the assumption that the backing storage is an os.File.
Operations ¶
The queue does not support the "pop" operation. This prevents callers from accidentally removing data from the queue before the operation that uses the data is successful.
The queue does not shrink as elements are removed. To shrink the queue, wait until its size drops to zero call Reset once or just it and create a new one.
Durability ¶
The queue is designed to be resilient against corruption from power loss and program crashes. For example, if an addition to the queue fails partway through, the queue will remain uncorrupted so long as the 32-byte queue header is updated atomically (or not at all). Queue operations are flushed to disk after each operation.
On macOS and iOS, operations are flushed to disk using fcntl(F_BARRIERFSYNC) instead of calling Sync. This is because Sync uses fcntl(F_FULLFSYNC) which (objectively) has horrendous performance and, according to Apple, usually isn't necessary. For more information, see Apple's documentation1.
Example usage (error handing is omitted for brevity):
q, _:= New(f)
q.Add([]byte("hello!"))
got, _ := q.Peek()
if string(got) == "hello!" {
// The data is correct, so pop it from the queue.
q.Remove()
}
It is heavily based off Square's Tape library0.
Index ¶
- Variables
- type CorruptedError
- type File
- type Option
- type Queue
- func (q *Queue) Add(data []byte) error
- func (q *Queue) Available() int64
- func (q *Queue) Cap() int64
- func (q *Queue) Len() int
- func (q *Queue) Peek() ([]byte, error)
- func (q *Queue) Range(fn func(p []byte) bool) error
- func (q *Queue) Remove(n int) error
- func (q *Queue) Reset() error
- func (q *Queue) Size() int64
- type Syncer
- type Truncater
Constants ¶
This section is empty.
Variables ¶
var ErrEmpty = errors.New("tape: queue is empty")
ErrEmpty is returned when the queue is empty.
Functions ¶
This section is empty.
Types ¶
type CorruptedError ¶
type CorruptedError struct {
// contains filtered or unexported fields
}
CorruptedError is returned when the queue has been corrupted.
func (*CorruptedError) Error ¶
func (e *CorruptedError) Error() string
func (*CorruptedError) Unwrap ¶
func (e *CorruptedError) Unwrap() error
type Option ¶
type Option func(*qopts)
Option configures a queue.
func WithNoSync ¶
func WithNoSync() Option
WithNoSync disables syncing the queue to permanent storge.
This should only be set in tests to make the disk-based tests quicker.
type Queue ¶
type Queue struct {
// contains filtered or unexported fields
}
Queue is a file-based FIFO queue.
func (*Queue) Available ¶
Available returns the number of bytes available for new queue elements before growing.
func (*Queue) Range ¶
Range calls fn for each element element in the queue, or until fn returns false.
The slice passed to the function is only valid until the function returns.
It is undefined behavior to call Add or Remove while iterating over the elements.
Source Files