=================
This Memory component is general purpose, has no external runtime dependencies and can be used in any application that needs to manage data structures inside or outside the Java heap.
Please visit the main DataSketches website for more information.
If you are interested in making contributions to this Memory component please see our Community page.
The goal of this component of the DataSketches library is to provide a high performance access API for accessing four different types of memory resources:
- On-heap Memory via primitive arrays
- On-heap Memory via ByteBuffers
- Off-heap (Direct or Native) Memory via direct allocation
- Off-Heap Memory-Mapped files
Each of the four resource types is accessed using different API methods in the Memory component.
Note: primitive := {byte, short, int, long, float, double}
-
Heap via primitive arrays:
- Memory.wrap(primitive[]) (read only)
- WritableMemory.allocate(int)
- WritableMemory.writableWrap(primitive[])
-
Heap via ByteBuffer
- Memory.wrap(ByteBuffer.wrap(byte[])) (read only)
- WritableMemory.writableWrap(ByteBuffer.allocate(int))
-
Off-Heap, Direct via direct allocation:
- WritableMemory.allocateDirect(long)
-
Off-Heap, Direct via (Direct) ByteBuffer
- WritableMemory.writableWrap(ByteBuffer.allocateDirect(int))
-
Off-Heap, Memory-Mapped Files
- Memory.map(File) (read only)
- WritableMemory.writableMap(File)
Starting with release datasketches-memory-5.0.0, this Memory component supports only Java 21 when compiling from source and should work with later Java versions at runtime.
- The DataSketches Java Memory Component is not thread-safe.
- We recommend Eclipse Adoptium/Temurin 21.0.5+11 or later as earlier releases of 21 have bugs that affect this product.
NOTES:
- This component accesses resource files for testing. As a result, the directory elements of the full absolute path of the target installation directory must qualify as Java identifiers. In other words, the directory elements must not have any space characters (or non-Java identifier characters) in any of the path elements. This is required by the Oracle Java Specification in order to ensure location-independent access to resources: See Oracle Location-Independent Access to Resources
- The compile command line must contain the JVM flag --enable-preview.
- This component is not designed as a Java Module, so the Jar file should be part of the application classpath.
There are no run-time dependencies. See the pom.xml file for test dependencies.
The Maven build requires JDK-21 to compile:
To run normal unit tests:
mvn clean test
To run javadoc:
mvn clean javadoc:javadoc -DskipTests=true
To run the eclipse plugin on this multi-module project, use:
mvn clean eclipse:eclipse -DskipTests=true
To install jars built from the downloaded source:
mvn clean install -DskipTests=true
This will create the following Jars:
- datasketches-memory-X.Y.Z.jar The compiled main class files.
- datasketches-memory-X.Y.Z-tests.jar The compiled test class files.
- datasketches-memory-X.Y.Z-sources.jar The main source files.
- datasketches-memory-X.Y.Z-test-sources.jar The test source files
- datasketches-memory-X.Y.Z-javadoc.jar The compressed Javadocs.
For releasing to Nexus, please use the sign-deploy-jar.sh
script in the scripts directory.
See the documentation within the script for usage instructions.