Package com.googlecode.cqengine.persistence.offheap

Class OffHeapPersistence<O,​A extends Comparable<A>>

  • All Implemented Interfaces:
    SQLitePersistence<O,​A>, Persistence<O,​A>, Closeable, AutoCloseable
    public class OffHeapPersistence<O,​A extends Comparable<A>>
extends Object
implements SQLitePersistence<O,​A>, Closeable
    Specifies that a collection or indexes should be persisted in native memory, within the JVM process but outside the Java heap.

    Each instance of this object specifies persistence to a different area of memory. So for example, to have an IndexedCollection and multiple indexes all persist to the same area of memory, configure them all to persist via the same instance of this object.

    Garbage collection
    The memory allocated off-heap will be freed automatically when this object is garbage collected. So using off-heap memory does not require any special handling per-se. This object will be garbage collected when any IndexedCollection or indexes using this object for persistence (which hold a reference to this object internally) are garbage collected, and the application also releases any direct reference to this object which it might be holding.

    Garbage collection - implementation details
    Internally this persistence strategy will open a connection to an in-memory SQLite database, and it will hold open a connection to that database until either this object is garbage collected, or the close() method is called explicitly. (The finalize() method of this object calls close() automatically.)

    This object provides additional connections to the database on-demand; which the IndexedCollection and indexes will request on-the-fly as necessary whenever the collection or indexes need to be read or updated. SQLite automatically frees the memory used by an in-memory database when the last connection to the database is closed. So by holding open a connection, this object keeps the in-memory database alive between requests.

    In terms of memory usage, the application can treat this as a very large object. The memory will be freed when this object is garbage collected, but the application can also free memory sooner by calling close(), but this is optional.

    Note on Concurrency
    Note that this persistence implementation (backed by an off-heap in-memory SQLite database) has more restrictive support for concurrency than other persistence implementations. This is because the concurrency support in SQLite is more limited in its in-memory mode than in its disk-based mode.

    Concurrent reads are supported when there are no ongoing writes, but writes are performed sequentially and they block all concurrent reads. Essentially the concurrency support is equivalent to that afforded by a ReadWriteLock.

    As a workaround, any applications requiring more concurrency with an in-memory persistence, for example concurrent reads and concurrent writes which don't block each other, could consider using DiskPersistence instead with the persistence file located on a ram disk.

    Author:
    niall.gallagher

    • Constructor Detail

    • Method Detail

      • getInstanceName

        public String getInstanceName()

      • supportsIndex

        public boolean supportsIndex​(Index<O> index)
        Description copied from interface: Persistence
        Checks if this persistence manages the given index.
        Specified by:
        supportsIndex in interface Persistence<O,​A extends Comparable<A>>
        Parameters:
        index - The Index for which a connection is required.
        Returns:
        True if the given index is an OffHeapTypeIndex. Otherwise false.

      • compact

        public void compact()
        Description copied from interface: SQLitePersistence
        Compacts the underlying persistence, which returns unused memory or disk space to the operating system.
        Specified by:
        compact in interface SQLitePersistence<O,​A extends Comparable<A>>

      • expand

        public void expand​(long numBytes)
        Description copied from interface: SQLitePersistence
        Expands the underlying persistence by the given number of bytes in a single operation. This will usually result in the persistence being expanded into an additional contiguous chunk of memory or region on disk.

        After this method returns, the operating system will report that the memory or disk space used for persistence has increased by this amount, but internally the space will simply be reserved for future use. The reserved space will be used to store objects added to the collection subsequently, without needing to request more memory from the OS ad-hoc.

        This can reduce fragmentation of the persistence file on some OS filesystems, especially if used prior to bulk imports when the persistence is on a non-SSD disk.

        Specified by:
        expand in interface SQLitePersistence<O,​A extends Comparable<A>>

      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class Object

      • createObjectStore

        public SQLiteObjectStore<O,​A> createObjectStore()
        Description copied from interface: Persistence
        Creates an ObjectStore which can store the objects added to the collection, either on-heap off-heap or on disk, depending on the persistence implementation.
        Specified by:
        createObjectStore in interface Persistence<O,​A extends Comparable<A>>
        Returns:
        An ObjectStore which persists objects added to the collection.

      • onPrimaryKey

        public static <O,​A extends Comparable<A>> OffHeapPersistence<O,​A> onPrimaryKey​(SimpleAttribute<O,​A> primaryKeyAttribute)
        Creates an OffHeapPersistence object which persists to native memory, within the JVM process but outside the Java heap.
        Parameters:
        primaryKeyAttribute - An attribute which returns the primary key of objects in the collection
        Returns:
        An OffHeapPersistence object which persists to native memory

      • onPrimaryKeyWithProperties

        public static <O,​A extends Comparable<A>> OffHeapPersistence<O,​A> onPrimaryKeyWithProperties​(SimpleAttribute<O,​A> primaryKeyAttribute,
                                                                                                         Properties overrideProperties)
        Creates an OffHeapPersistence object which persists to native memory, within the JVM process but outside the Java heap.
        Parameters:
        primaryKeyAttribute - An attribute which returns the primary key of objects in the collection
        overrideProperties - Optional properties to override default settings (can be empty to use all default settings, but cannot be null)
        Returns:
        An OffHeapPersistence object which persists to native memory