Off-heap memory tools based on sun.misc.Unsafe
Some tools to work with off-heap memory using sun.misc.Unsafe
class. Contains fallback
implementations for environments, where proper implementation of sun.misc.Unsafe
is not available.
All memory access code has boundary checks using assert keyword.
With assertions enabled in runtime (-ea
java switch) illegal memory access will throw AssertionError
.
Without assertions illegal memory access will crash JVM.
Library has no third-party dependencies and is available in Maven central:
<dependency>
<groupId>com.alexkasko.unsafe</groupId>
<artifactId>unsafe-tools</artifactId>
<version>1.2.3</version>
</dependency>
Off-heap memory, data structures, operations
JVM allows to allocate and use memory outside of java heap. Such off-heap memory is not managed by garbage collector and may be allocated using
public API: ByteBuffer.allocateDirect.
In OpenJDK (and in Oracle java) direct bytes buffers use sun.misc.Unsafe
under the hood to work with off-heap memory.
###Off-heap memory management
All off-heap data structures in this library are based on OffHeapMemory. It has two implementations:
- main implementation: thin wrapper over
sun.misc.Unsafe
with boundary checks usingassert
keyword - fallback implementation: wrapper over
ByteBuffer.allocateDirect
Both implementations have the same methods, but DirectByteBuffer
(fallback) implementation has some drawbacks and
should be used only if proper implementation of sun.misc.Unsafe
is not available in runtime (i.e. in Android's Dalvik VM):
- mandatory boundary checks
- each memory allocation is limited by
Integer.MAX_VALUE
- by default off-heap memory is freed only when
DirectByteBuffer
is garbage collector; this library uses reflection hacks (different for OpenJDK and Android implementations) to free memory eagerly
###Off-heap data structures
Off-heap data structures have next distinctive features:
- off-heap collections may use long indexes (not bounded by
Integer.MAX_VALUE
) - GC doesn't know about allocated memory so you can allocate gigabytes of memory without additional load on GC
- memory may be freed to OS eagerly (it's not mandatory,
OffHeapMemory
will free memory when it's instance will be garbage collected)
Off-heap collections with long
elements:
- long indexed fixed-size arrays of
long
(javadoc, usage) - long indexed growing array-lists of
long
(javadoc, usage)
Off-heap collections where each element contains long
'header' and an additional 'payload' value:
- long indexed fixed-size header-payload (each element contain
long
header andbyte[]
payload) arrays (javadoc, usage) - long indexed growing header-payload array-lists (javadoc, usage)
- long indexed fixed-size header-int_payload (each element contain
long
header andint
payload) arrays (javadoc, usage) - long indexed growing header-int_payload array-lists (javadoc, usage)
- long indexed fixed-size header-long_payload (each element contain
long
header andlong
payload) arrays (javadoc, usage) - long indexed growing header-long_payload array-lists (javadoc, usage)
Payloads are stored in memory next to headers. Byte arrays of arbitrary size may be used as payloads for storing non-primitive values.
Special collections for long
and int
payloads should be faster than byte[]
ones.
###Operations
Next operations are implemented for all off-heap data structures:
- Dual-Pivot Quicksort implementation, adapted from here
- Binary Search implementation, adapted from here
Byte array tool
sun.misc.Unsafe
may be used for writing/reading primitive values to/from byte arrays and to copying memory between byte arrays.
Such operations use platform byte order (little endian usually) and does not have boundary checks.
ByteArrayTool
(javadoc,
usage)
was created on top of such operations with assert
boundary checks. It uses little endian bit-shifting as fallback implementation.
License information
This project is released under the Apache License 2.0
Changelog
1.2.3 (2013-05-06)
- improve
assert
checks for off-heap memory - binary search javadoc fixes
1.2.2 (2013-04-28)
- prevent result object instantiation in ranged search
1.2.1 (2013-04-28)
- ranges support for binary search
1.2 (2013-04-25)
- bug fixed in
OffHeapPayloadSorter
- in some circumstances in 1.1 sorting may overwrite payload values for equal headers. A lot of tests on random data have been run to check correctness of 1.2 version - header-int_payload array, array list and sorting
- header-long_payload array, array list and sorting
1.1 (2013-03-05)
- long-array list
- header-payload array and array list
- binary search for all collections
1.0 (2013-02-24)
- initial version