commit	dda60cecdebce9d1932378a63a2b35024fb85491	[log] [tgz]
author	Lee Rhodes <leerho@users.noreply.github.com>	Fri Oct 11 15:27:17 2024 -0700
committer	GitHub <noreply@github.com>	Fri Oct 11 15:27:17 2024 -0700
tree	8911e47eaa5e33f1840dfbc9c05ba73fc9539fdc
parent	66997503c2a7428441205cffc3a9104f5f0215e0 [diff]
parent	2a08f94da83727b2e301bd42e76ff406e6dad1f9 [diff]

tree: 8911e47eaa5e33f1840dfbc9c05ba73fc9539fdc

README.md

=================

DataSketches Java Memory Component

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) 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}

Contiguous bytes on the Java Heap constructed by these examples:

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))

Contiguous bytes off the Java Heap constructed by these examples:

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)

Release 4.0.0 (inclusive) to 5.0.0 (exclusive)

Starting with release datasketches-memory-4.0.0, this Memory component supports Java 17 when compiling from source and should work with later Java versions at runtime. This component is not designed as a Java Module, so the Jar file should be part of the application classpath.

Build Instructions

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 --add-modules=jdk.incubator.foreign.
This component is not designed as a Java Module, so the Jar file should be part of the application classpath.

Dependencies

There are no run-time dependencies. See the pom.xml file for test dependencies.

Maven build instructions

The Maven build requires JDK-17 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.

Deployment to Nexus

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.