Package 

Class QueueFile

  • All Implemented Interfaces:
    java.io.Closeable , java.lang.AutoCloseable 
    
public class QueueFile
 implements Closeable

    A reliable, efficient, file-based, FIFO queue. Additions and removals are O(1). All operations are atomic. Writes are synchronous; data will be written to disk before an operation returns. The underlying file is structured to survive process and even system crashes. If an I/O exception is thrown during a mutating change, the change is aborted. It is safe to continue to use a {@code * QueueFile} instance after an exception.

    All operations are synchronized. In a traditional queue, the remove operation returns an element. In this queue, peek and remove are used in conjunction. Use {@code * peek} to retrieve the first element, and then {@code remove} to remove it after successful processing. If the system crashes after {@code peek} and during processing, the element will remain in the queue, to be processed when the system restarts.

    NOTE: The current implementation is built for file systems that support atomic segment writes (like YAFFS). Most conventional file systems don't support this; if the power goes out while writing a segment, the segment will contain garbage and the file will be corrupt. We'll add journaling support so this class can be used with more file systems later.

    • Constructor Summary

      Constructors 
      Constructor Description
      QueueFile(File file) Constructs a new queue backed by the given file.

    • Method Summary

      Modifier and Type Method Description
      void add(Array<byte> data) Adds an element to the end of the queue.
      synchronized void add(Array<byte> data, int offset, int count) Adds an element to the end of the queue.
      synchronized boolean isEmpty() Returns true if this queue contains no entries.
      synchronized Array<byte> peek() Reads the eldest element.
      synchronized int forEach(PayloadQueue.ElementVisitor reader) Invokes the given reader once for each element in the queue, from eldest to most recentlyadded.
      synchronized int size() Returns the number of elements in this queue.
      synchronized void remove() Removes the eldest element.
      synchronized void remove(int n) Removes the eldest {@code n} elements.
      synchronized void clear() Clears this queue.
      synchronized void close() Closes the underlying file.
      String toString()

      • Methods inherited from class java.io.Closeable

        close

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Constructor Detail

      • QueueFile

        QueueFile(File file)
        Constructs a new queue backed by the given file.

    • Method Detail

      • add

         void add(Array<byte> data)

        Adds an element to the end of the queue.

        Parameters:
        data - to copy bytes from

      • add

         synchronized void add(Array<byte> data, int offset, int count)

        Adds an element to the end of the queue.

        Parameters:
        data - to copy bytes from
        offset - to start from in buffer
        count - number of bytes to copy

      • isEmpty

         synchronized boolean isEmpty()

        Returns true if this queue contains no entries.

      • peek

         synchronized Array<byte> peek()

        Reads the eldest element. Returns null if the queue is empty.

      • forEach

         synchronized int forEach(PayloadQueue.ElementVisitor reader)

        Invokes the given reader once for each element in the queue, from eldest to most recentlyadded. Continues until all elements are read or reader.read() returns {@code false}.

      • size

         synchronized int size()

        Returns the number of elements in this queue.

      • remove

         synchronized void remove()

        Removes the eldest element.

      • remove

         synchronized void remove(int n)

        Removes the eldest {@code n} elements.

      • clear

         synchronized void clear()

        Clears this queue. Truncates the file to the initial size.

      • close

         synchronized void close()

        Closes the underlying file.