README.md

BytesFIFO

Introduction

This module contains exactly two classes, BytesFIFO and ThreadsafeBytesFIFO. The purpose of BytesFIFO is to provide a stream-like interface to a fixed-size byte-oriented FIFO in Python. This should be significantly faster than using a deque, list, or manually manipulating str/bytearray/bytes. ThreadsafeBytesFIFO does the same thing as BytesFIFO, but is thread-safe. It depends on the threading module, and will only be available if this module can be imported.

The API only accepts bytes and bytearray, and will read data back as bytes. It is a non-blocking stream.

Performance

Preliminary performance analysis shows that Python 2.7 is about 25% faster than Python 3.4 when reading and writing large chunks of data to the FIFO.

Examples

Creating a FIFO

A FIFO is created with a fixed size. The internal buffer is completely pre-allocated.

# Create a 5 kB FIFO
f = fifo.BytesFIFO(5*1024)

Filling the FIFO

f.write(b"Here's some data")
f.write(b"More data!")
# Consume all data
d = f.read(len(f))

Querying the FIFO state

f.full()     # Is the FIFO completely filled?
f.empty()    # Is the FIFO completely empty?
f.free()     # How much data is left in the FIFO?
f.capacity() # How much data can the FIFO hold?
len(f)       # How much data is filled in the FIFO?
bool(f)      # Is the FIFO non-empty?

Resizing

The FIFO may be expanded or contracted. All data is retained after the resize operation, but a copy operation may be occur. ValueError is raised if the resize operation would cause data loss.

f = fifo.BytesFIFO(10)
f.write(b"Testing")
f.resize(20)
# returns b"Testing"
f.read(len(f))

Writing more data than allocated

f = fifo.BytesFIFO(5)
# Only b"Lorem" is written, since the FIFO depth is 5 bytes.
bytes_written = f.write(b"Lorem ipsum dolor sit amet, consectetur adipiscing elit")
data = f.read(5)