Package io.sentry.cache.tape

Class QueueFile

java.lang.Object
io.sentry.cache.tape.QueueFile
All Implemented Interfaces:
Closeable, AutoCloseable, Iterable<byte[]>
@Internal public final class QueueFile extends Object implements Closeable, Iterable<byte[]>
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 QueueFile instance after an exception.

Note that this implementation is not synchronized.

In a traditional queue, the remove operation returns an element. In this queue, peek() and remove() are used in conjunction. Use peek to retrieve the first element, and then remove to remove it after successful processing. If the system crashes after 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.

Construct instances with QueueFile.Builder.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static final class 
    QueueFile.Builder
    Fluent API for creating QueueFile instances.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    add(byte[] data)
    Adds an element to the end of the queue.
    void
    add(byte[] data, int offset, int count)
    Adds an element to the end of the queue.
    void
    clear()
    Clears this queue.
    void
    close()
     
    File
    file()
    The underlying File backing this queue.
    boolean
    isAtFullCapacity()
    Returns true if the capacity limit of this queue has been reached, i.e.
    boolean
    isEmpty()
    Returns true if this queue contains no entries.
    Iterator<byte[]>
    iterator()
    Returns an iterator over elements in this QueueFile.
    @org.jetbrains.annotations.Nullable byte[]
    peek()
    Reads the eldest element.
    void
    remove()
    Removes the eldest element.
    void
    remove(int n)
    Removes the eldest n elements.
    int
    size()
    Returns the number of elements in this queue.
    String
    toString()
     

    Methods inherited from class java.lang.Object

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

    Methods inherited from interface java.lang.Iterable

    forEach, spliterator

  • Method Details

    • add

      public void add(byte[] data) throws IOException
      Adds an element to the end of the queue.
      Parameters:
      data - to copy bytes from
      Throws:
      IOException

    • add

      public void add(byte[] data, int offset, int count) throws IOException
      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
      Throws:
      IndexOutOfBoundsException - if offset < 0 or count < 0, or if offset + count is bigger than the length of buffer.
      IOException

    • isEmpty

      public boolean isEmpty()
      Returns true if this queue contains no entries.

    • peek

      @Nullable public @org.jetbrains.annotations.Nullable byte[] peek() throws IOException
      Reads the eldest element. Returns null if the queue is empty.
      Throws:
      IOException

    • iterator

      public Iterator<byte[]> iterator()
      Returns an iterator over elements in this QueueFile.

      The iterator disallows modifications to be made to the QueueFile during iteration. Removing elements from the head of the QueueFile is permitted during iteration using Iterator.remove().

      The iterator may throw an unchecked IOException during Iterator.next() or Iterator.remove().

      Specified by:
      iterator in interface Iterable<byte[]>

    • size

      public int size()
      Returns the number of elements in this queue.

    • remove

      public void remove() throws IOException
      Removes the eldest element.
      Throws:
      NoSuchElementException - if the queue is empty
      IOException

    • remove

      public void remove(int n) throws IOException
      Removes the eldest n elements.
      Throws:
      NoSuchElementException - if the queue is empty
      IOException

    • clear

      public void clear() throws IOException
      Clears this queue. Truncates the file to the initial size.
      Throws:
      IOException

    • isAtFullCapacity

      public boolean isAtFullCapacity()
      Returns true if the capacity limit of this queue has been reached, i.e. the number of elements stored in the queue equals its maximum size.
      Returns:
      true if the capacity limit has been reached, false otherwise

    • file

      public File file()
      The underlying File backing this queue.

    • close

      public void close() throws IOException
      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface Closeable
      Throws:
      IOException

    • toString

      public String toString()
      Overrides:
      toString in class Object