Package com.illumon.iris.db.v2.locations

Class FileDataBufferStore

java.lang.Object
com.illumon.iris.db.v2.locations.FileDataBufferStore
public final class FileDataBufferStore
extends Object
Ordered buffer tracking system for a file, used to represent the data region of a column file. Allows thread safe, concurrent access by multiple readers and a single writer.

TODO: Address "missed" pooling opportunities if/when they contribute significantly to server GC: (1) Buffer duplicate views. (2) Buffer read-only views. (3) Messages.

  • Field Details

  • Constructor Details

    • FileDataBufferStore

      public FileDataBufferStore​(@NotNull FileAccessor fileAccessor, @NotNull ByteOrder byteOrder)
      Construct a non-writable store.
      Parameters:
      fileAccessor - An accessor for the file (or file region) that we're presenting a buffered view of
      byteOrder - The byte order that should be used for all buffers in this store

    • FileDataBufferStore

      public FileDataBufferStore​(@NotNull FileAccessor fileAccessor, @NotNull ByteOrder byteOrder, long initialSize, boolean writable)
      Construct an optionally-writable store.
      Parameters:
      fileAccessor - An accessor for the file (or file region) that we're presenting a buffered view of
      byteOrder - The byte order that should be used for all buffers in this store
      initialSize - Initially known visible size of the underlying file (or file region)
      writable - Whether this store should allow writing (buffer accept)

  • Method Details

    • toString

      public final String toString()
      Overrides:
      toString in class Object

    • releaseCachedResources

      public final void releaseCachedResources()

      Release any resources held for caching purposes. This is primarily intended for applications that know they will no longer use a given data store.

      This is perfectly safe for concurrent use in read-only applications, although it may result in repeated reads that would otherwise be unnecessary, and may cause repeated reads to be recorded as first time reads by the performance instrumentation sub-system.

      Writers should be careful to avoid having outstanding buffers before invoking this.

    • size

      public final long size()
      Get the current known visible size of the file data backing this store, in bytes.
      Returns:
      The current known visible size of the file data backing this store, in bytes.

    • getUpdatedSize

      public final long getUpdatedSize()
      Force an update to the size if possible, and fetch the result.
      Returns:
      The resulting size

    • ensureSize

      public final void ensureSize​(long requiredSize)
      Make sure size is large enough to accommodate a request. Call before proceeding with any request.
      Parameters:
      requiredSize - The size required by the caller in order to make progress

    • force

      public final void force()
      Ensure that all contents written to the store have been persisted.

    • getMessageViewByOffset

      public final FileDataBufferStore.StoredBufferMessage getMessageViewByOffset​(long startOffset, int minimumLength)
      Present a Message view of the implied buffer, with views positioned accordingly. The result should be "released" using Message.finished(), per the usual usage of Message objects.
      Parameters:
      startOffset - 0 <= startOffset
      minimumLength - 0 < minimumLength <= getBufferSize()
      Returns:
      A Message for use in transmission via an IOJob.

    • provideBufferReferenceByIndex

      public final PooledObjectReference<DataBufferHolder> provideBufferReferenceByIndex​(int bufferIndex, int requiredLimit)

      Get an acquired PooledObjectReference to the specified buffer's DataBufferHolder, and ensure that the current buffer (see DataBufferHolder.getCurrent()) is filled enough to accommodate the supplied limit.

      The referent's current view will be positioned for reading all available data, and should only be accessed via positional "get" methods - hand a read-only view (see DataBufferHolder.readOnlyView()) to untrusted code, or a writable view (see DataBufferHolder.writableView()) to code that will write new contents for a later call to acceptBufferByIndex(PooledObjectReference, int, ByteBuffer, int).

      The caller is responsible for calling PooledObjectReference.release() on the returned reference when it's done.

      Parameters:
      bufferIndex - The buffer's index.
      requiredLimit - The limit required by the caller.
      Returns:
      An acquired PooledObjectReference to a non-null DataBufferHolder whose current view has capacity == getBufferSize() and 0 <= requiredLimit <= limit

    • enableReleaseTracking

      public static PooledObjectReference.Tracker<DataBufferHolder> enableReleaseTracking()
      Enable release tracking if not already enabled, and get the release tracker.
      Returns:
      The release tracker

    • disableReleaseTracking

      public static PooledObjectReference.Tracker<DataBufferHolder> disableReleaseTracking()
      Disable release tracking if enabled, and get the release tracker.
      Returns:
      The release tracker, possibly null

    • acceptBufferByIndex

      public final void acceptBufferByIndex​(PooledObjectReference<DataBufferHolder> holderRef, int bufferIndex, ByteBuffer inputBuffer, int pendingPosition)

      Accept a buffer for writing through to the store and underlying file, extending the size as needed. The buffer must be positioned to read the region to be accepted, must be a duplicate of holderRef's current referent, and *must* no longer be accessed externally unless through a view/duplicate. The holderRef must have been acquired by or on-behalf-of the caller, and must not be released concurrently with this invocation.

      This method does not release holderRef on behalf of the caller - the caller very well may create another duplicate to fill, for example.

      pendingPosition must be NULL_PENDING_POSITION or a value such that inputBuffer.position() <= pendingPosition < inputBuffer.limit(). Such content is provisionally accepted but not made visible to readers until promotePending() is invoked.

      Parameters:
      holderRef - The pooled reference corresponding to the supplied buffer index (only used for verification)
      bufferIndex - The buffer's index
      inputBuffer - The ByteBuffer to accept
      pendingPosition - If non-null, the position from which to treat inputBuffer's contents as pending

    • promotePending

      public void promotePending()
      Make previously-accepted pending data part of the visible region of the store.

    • revertPending

      public void revertPending()
      Release resources associated with previously-accepted pending data, and truncate the pending region of the underlying file.