You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@datasketches.apache.org by dc...@apache.org on 2021/08/16 20:34:22 UTC
[datasketches-memory] branch documentation-updates updated (c5c883b
-> 0e0ee40)
This is an automated email from the ASF dual-hosted git repository.
dcromberge pushed a change to branch documentation-updates
in repository https://gitbox.apache.org/repos/asf/datasketches-memory.git.
discard c5c883b Documentation updates
add b4b17f1 Interim commit
add dfa2e92 This passes all tests. Need to check coverage.
add 543b461 More clean up
add 16c6f9e Fixes this issue, but we still have a leak.
add ab72832 Fix #2, keep trying.
add f5ddc7d Possible leak points. Not sure
add bcc87ff Merge pull request #139 from apache/MajorRefactorAndFix
new 0e0ee40 Documentation updates
This update added new revisions after undoing existing revisions.
That is to say, some revisions that were in the old version of the
branch are not in the new version. This situation occurs
when a user --force pushes a change and generates a repository
containing something like this:
* -- * -- B -- O -- O -- O (c5c883b)
\
N -- N -- N refs/heads/documentation-updates (0e0ee40)
You should already have received notification emails for all of the O
revisions, and so the following emails describe only the N revisions
from the common base, B.
Any revisions marked "omit" are not gone; other references still
refer to them. Any revisions marked "discard" are gone forever.
The 1 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
Summary of changes:
.../memory/test/AllocateDirectMemoryTest.java | 22 +-
.../test/AllocateDirectWritableMapMemoryTest.java | 12 +-
.../datasketches/memory/test/BaseBufferTest.java | 8 +-
.../datasketches/memory/test/Buffer2Test.java | 2 +-
.../memory/test/BufferInvariantsTest.java | 2 +-
.../memory/test/BufferReadWriteSafetyTest.java | 2 +-
.../memory/test/DruidIssue11544Test.java | 61 ++--
.../test/ExampleMemoryRequestServerTest.java | 64 ++--
.../datasketches/memory/test/LeafImplTest.java | 54 ++--
.../memory/test/MemoryReadWriteSafetyTest.java | 2 +-
.../datasketches/memory/test/MemoryTest.java | 108 +++----
.../memory/test/NativeWritableBufferImplTest.java | 26 +-
.../memory/test/NativeWritableMemoryImplTest.java | 4 +-
.../datasketches/memory/test/SpecificLeafTest.java | 58 ++--
.../memory/test/WritableMemoryTest.java | 12 +-
.../datasketches/memory/test/ZeroCapacityTest.java | 7 +-
.../org/apache/datasketches/memory/BaseState.java | 2 +-
.../org/apache/datasketches/memory/Buffer.java | 63 ++--
.../memory/DefaultMemoryRequestServer.java | 10 +-
.../org/apache/datasketches/memory/Handle.java | 2 +-
.../org/apache/datasketches/memory/Memory.java | 296 +++++++----------
.../datasketches/memory/MemoryRequestServer.java | 15 +-
.../memory/{internal => }/ReadOnlyException.java | 4 +-
.../apache/datasketches/memory/WritableBuffer.java | 81 +++--
.../apache/datasketches/memory/WritableMemory.java | 355 +++++++++++----------
.../memory/internal/AllocateDirectWritableMap.java | 1 +
.../internal/BBNonNativeWritableBufferImpl.java | 40 ++-
.../internal/BBNonNativeWritableMemoryImpl.java | 25 +-
.../memory/internal/BBWritableBufferImpl.java | 40 ++-
.../memory/internal/BBWritableMemoryImpl.java | 25 +-
.../memory/internal/BaseBufferImpl.java | 1 +
.../memory/internal/BaseStateImpl.java | 29 +-
.../memory/internal/BaseWritableBufferImpl.java | 101 +++---
.../memory/internal/BaseWritableMemoryImpl.java | 116 ++-----
.../datasketches/memory/internal/BufferImpl.java | 162 ----------
.../DirectNonNativeWritableBufferImpl.java | 41 +--
.../DirectNonNativeWritableMemoryImpl.java | 25 +-
.../memory/internal/DirectWritableBufferImpl.java | 41 +--
.../memory/internal/DirectWritableMemoryImpl.java | 25 +-
.../internal/HeapNonNativeWritableBufferImpl.java | 37 ++-
.../internal/HeapNonNativeWritableMemoryImpl.java | 26 +-
.../memory/internal/HeapWritableBufferImpl.java | 37 ++-
.../memory/internal/HeapWritableMemoryImpl.java | 28 +-
.../internal/MapNonNativeWritableBufferImpl.java | 34 +-
.../internal/MapNonNativeWritableMemoryImpl.java | 19 +-
.../memory/internal/MapWritableBufferImpl.java | 34 +-
.../memory/internal/MapWritableMemoryImpl.java | 19 +-
.../datasketches/memory/internal/MemoryImpl.java | 225 -------------
.../memory/internal/NativeWritableBufferImpl.java | 8 +-
.../memory/internal/NativeWritableMemoryImpl.java | 4 +-
.../internal/NonNativeWritableBufferImpl.java | 8 +-
.../internal/NonNativeWritableMemoryImpl.java | 4 +-
.../apache/datasketches/memory/internal/Utf8.java | 6 +-
.../apache/datasketches/memory/internal/Util.java | 24 +-
.../memory/internal/WritableBufferImpl.java | 170 ----------
.../memory/internal/WritableMapHandleImpl.java | 3 +-
.../memory/internal/WritableMemoryImpl.java | 254 ---------------
datasketches-memory-resources/pom.xml | 5 +-
58 files changed, 1054 insertions(+), 1835 deletions(-)
rename datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/{internal => }/ReadOnlyException.java (90%)
delete mode 100644 datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/internal/BufferImpl.java
delete mode 100644 datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/internal/MemoryImpl.java
delete mode 100644 datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/internal/WritableBufferImpl.java
delete mode 100644 datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/internal/WritableMemoryImpl.java
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@datasketches.apache.org
For additional commands, e-mail: commits-help@datasketches.apache.org
[datasketches-memory] 01/01: Documentation updates
Posted by dc...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
dcromberge pushed a commit to branch documentation-updates
in repository https://gitbox.apache.org/repos/asf/datasketches-memory.git
commit 0e0ee4066fa493b784766e83f978d145e173818d
Author: David Cromberge <dc...@apache.org>
AuthorDate: Mon Aug 16 21:33:55 2021 +0100
Documentation updates
Provide additional usage instructions for users who
may use the library in different configurations.
These scenarious are outlined together with sample
scripts demonstrating the required JPMS arguments for
each, if and when they are applicable.
---
README.md | 65 ++++-------
datasketches-memory-resources/pom.xml | 5 +-
docs/eclipse.md | 5 +-
docs/intellij.md | 3 +
docs/maven-toolchains.md | 9 +-
docs/maven.md | 2 +-
docs/module-system.md | 34 +-----
docs/multi-release-jar.md | 7 +-
docs/usage-instructions.md | 203 ++++++++++++++++++++++++++++++++++
9 files changed, 248 insertions(+), 85 deletions(-)
diff --git a/README.md b/README.md
index 92a028b..66943e2 100644
--- a/README.md
+++ b/README.md
@@ -39,56 +39,30 @@ If you are interested in making contributions to this site please see our
---
## Java Support
+Datasketches Memory currently supports Java 8 up to and including Java 13.
-Datasketches memory currently supports Java 8 up to and including Java 13.
-
-In order to allocate off-heap memory using the library in Java 9 and above, you must provide the
-following runtime arguments to the JVM:
-
-```shell
- --add-opens java.base/java.nio=org.apache.datasketches.memory \
- --add-opens java.base/jdk.internal.misc=org.apache.datasketches.memory \
- --add-opens java.base/jdk.internal.ref=org.apache.datasketches.memory
-```
-
-For example, to run your local application with full compatibility for the Java module system,
-you might use the following command:
-
-```shell
- $JAVA \
- --module-path mods \
- --add-opens java.base/java.nio=org.apache.datasketches.memory \
- --add-opens java.base/jdk.internal.misc=org.apache.datasketches.memory \
- --add-opens java.base/jdk.internal.ref=org.apache.datasketches.memory \
- --module my.main.application.module
-```
-
-where `mods` is your module path and `my.main.application.module` is your own JPMS module:
-
-```java
-module datasketches.memory.multirelease.test {
- requires org.apache.datasketches.memory;
-}
-```
-
-Note that the `add-opens` arguments are not required for cases where memory is allocated on the
-heap.
+__NOTE:__ You may have to provide additional JPMS arguments in order to use the library in Java 9 and above,
+see the [usage instructions](docs/usage-instructions.md) for details.
---
## Build Instructions
-__NOTE:__ 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](https://docs.oracle.com/javase/8/docs/technotes/guides/lang/resources.html)
-
-__IMPORTANT:__ This project is structured as a maven multi-module project.
-Building this project might affect plugins that require early dependency resolution, such as the
-javadoc and eclipse plugins. The build instructions below have been modified to use the
-`process-classes` phase (instead of `compile`) for these use cases. For more information,
-see this [Maven Reactor Issue](https://issues.apache.org/jira/browse/MNG-3283).
+__NOTE:__
+
+1) 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](https://docs.oracle.com/javase/8/docs/technotes/guides/lang/resources.html)
+
+2) This project is structured as a Maven multi-module project.
+ Building this project might affect plugins that require early dependency resolution, such as the
+ javadoc and eclipse plugins.
+ The build instructions below have been modified to use the `process-classes` phase (instead of `compile`)
+ for these use cases.
+
+ For more information, see this [Maven Reactor Issue](https://issues.apache.org/jira/browse/MNG-3283).
### JDK versions required to compile
This DataSketches component is pure Java and requires the following JDKs to compile:
@@ -158,6 +132,7 @@ detail:
* [Maven Toolchains Configuration](docs/maven-toolchains.md)
* [Multi-Release Jar](docs/multi-release-jar.md)
* [Java Platform Module System](docs/module-system.md)
+* [Usage instructions](docs/usage-instructions.md)
In order to build and contribute to this project, please read the relevant IDE documentation:
diff --git a/datasketches-memory-resources/pom.xml b/datasketches-memory-resources/pom.xml
index 8ecc482..7f67a28 100644
--- a/datasketches-memory-resources/pom.xml
+++ b/datasketches-memory-resources/pom.xml
@@ -169,9 +169,10 @@
<configuration>
<skip>false</skip>
<argLine>
+ --add-exports java.base/jdk.internal.misc=ALL-UNNAMED
+ --add-exports java.base/jdk.internal.ref=ALL-UNNAMED
--add-opens java.base/java.nio=ALL-UNNAMED
- --add-opens java.base/jdk.internal.misc=ALL-UNNAMED
- --add-opens java.base/jdk.internal.ref=ALL-UNNAMED
+ --add-opens java.base/sun.nio.ch=ALL-UNNAMED
</argLine>
<dependenciesToScan>
<dependency>org.apache.datasketches:datasketches-memory-java8-tests</dependency>
diff --git a/docs/eclipse.md b/docs/eclipse.md
index 8edfc1b..ccea301 100644
--- a/docs/eclipse.md
+++ b/docs/eclipse.md
@@ -24,6 +24,9 @@ The use of Maven submodules to build a Multi Release JAR was motivated by its co
popular IDEs. There are two configuration properties to be aware of when configuring your local
development environment:
+1) Java compiler versions
+2) Compiler arguments for JPMS
+
### Java compiler versions
Settings are usually synchronised with Maven Toolchain configuration, otherwise the Java version
@@ -78,7 +81,7 @@ Please note that this plugin is retired and no longer maintained!
From the **Package Explorer** View:
-- Right click on a blank space in the view
+- Right-click on a blank space in the view
- Select **Import/Maven/Existing Maven Projects**
- Select **Next**, and browse to the project directory
- Click **Open**
diff --git a/docs/intellij.md b/docs/intellij.md
index 7b77219..19b9894 100644
--- a/docs/intellij.md
+++ b/docs/intellij.md
@@ -25,6 +25,9 @@ popular IDEs.
There are two configuration properties to be aware of when configuring your local development
environment:
+1) Java compiler versions
+2) Compiler arguments for JPMS
+
#### Java compiler versions
Settings are usually synchronised with maven toolchain configuration, otherwise the Java version
diff --git a/docs/maven-toolchains.md b/docs/maven-toolchains.md
index f36cb8c..26ad6b1 100644
--- a/docs/maven-toolchains.md
+++ b/docs/maven-toolchains.md
@@ -31,7 +31,7 @@ From the [maven-toolchain-plugin documentation](https://maven.apache.org/plugins
### Motivation
Toolchains are used in different maven modules to ensure that the correct Java compiler version
-is used when compiling source files. This is because `datasketches-memory` uses some JDK
+is used when compiling source files. This is because Datasketches Memory uses some JDK
version-specific APIs, which require different JDKs to compile correctly.
### Toolchains template
@@ -48,7 +48,7 @@ the requisite entries should be merged into the existing file if they do not alr
### Environment variables
-The `dataSketches-memory` component is pure Java and requires the following JDKs to compile:
+The DataSketches Memory component is pure Java and requires the following JDKs to compile:
- JDK8/Hotspot
- JDK9/Hotspot
@@ -73,8 +73,7 @@ might be configured as follows:
Users can discover what JDKs have been loaded into their environment by using the following
command:
-- /usr/libexec/java_home -V
-
+ /usr/libexec/java_home -V
### Eclipse configuration
@@ -83,5 +82,5 @@ appropriate JDK for each module - see the [Eclipse IDE Setup](eclipse.md).
### IntelliJ configuration
-Similarly, if you are an Eclipse user, you may need further configuration for your IDE to use the
+Similarly, if you are an IntelliJ user, you may need further configuration for your IDE to use the
appropriate JDK for each module - see the [IntelliJ IDE Setup](intellij.md).
diff --git a/docs/maven.md b/docs/maven.md
index c33e3f3..7bf7ec5 100644
--- a/docs/maven.md
+++ b/docs/maven.md
@@ -23,7 +23,7 @@ This project is a multi-module Maven project. A multi-module Maven project consi
aggregator project (the `datasketches-memory-root` project), together with a set of submodules.
The aggregator's configuration is inherited by each submodule, thus reducing duplication.
-`datasketches-memory` makes use of some features of the Java platform, for example, `Unsafe`,
+Datasketches Memory makes use of some features of the Java platform, for example, `Unsafe`,
which have evolved in Java versions 9 and above. Therefore, a multi-module project allows us to
add support for later versions of Java by using independent Maven modules to target
platform-specific APIs. For example, to deallocate references a `sun.misc.Cleaner` will be used
diff --git a/docs/module-system.md b/docs/module-system.md
index fea7048..2991985 100644
--- a/docs/module-system.md
+++ b/docs/module-system.md
@@ -40,7 +40,7 @@ components, and which are not;
JDK internals are now strongly encapsulated, except for critical internal APIs such as
`sun.misc.Unsafe` (see [JEP-396](https://openjdk.java.net/jeps/396) and
[JEP-403](https://openjdk.java.net/jeps/403)).
-`datasketches-memory` can no longer access these APIs by default, and requires explicit access.
+Datasketches Memory can no longer access these APIs by default, and requires explicit access.
### Module declarations
@@ -59,28 +59,13 @@ module org.apache.datasketches.memory {
requires jdk.unsupported;
exports org.apache.datasketches.memory;
- exports org.apache.datasketches.memory.internal to org.apache.datasketches.memory.tests;
}
```
-This declaration explicitly defines the dependencies for `datasketches-memory`, as well as the
+This declaration explicitly defines the dependencies for the `org.apache.datasketches.memory` module, as well as the
external API. The `org.apache.datasketches.internal` package is now inaccessible to the end user,
providing better encapsulation.
-#### org.apache.datasketches.memory.tests
-
-The module declaration above makes provision for unit testing.
-The `org.apache.datasketches.internal` package is not accessible to the end user,
-but is accessible to the `org.apache.datasketches.memory.tests` module:
-
-```java
-module org.apache.datasketches.memory.tests {
- requires java.base;
- requires org.testng;
- requires org.apache.datasketches.memory;
-}
-```
-
### Compiler arguments
Some dependencies are encapsulated by default, and this causes compilation to fail for
@@ -88,7 +73,7 @@ Java versions 9 and above.
These dependencies can be made accessible at compile time through the use of the
`add-exports` compiler argument.
This argument allows one module to access some of the unexported types of another module.
-Datasketches memory has come to depend on several internal APIs and therefore requires special
+Datasketches Memory has come to depend on several internal APIs and therefore requires special
exposition.
For example, in order to compile the `datasketches-memory-java9` submodule, the following compiler
@@ -108,18 +93,11 @@ where fields and methods that do not have `public` visibility in a class.
Reflective access requires additional arguments to be provided by the user at runtime,
in order to use the `datasketches-memory` JPMS module in Java versions 9 and above.
-The following runtime arguments should be provided when allocating memory off-heap:
-
-```shell
- --add-opens java.base/java.nio=org.apache.datasketches.memory \
- --add-opens java.base/jdk.internal.misc=org.apache.datasketches.memory \
- --add-opens java.base/jdk.internal.ref=org.apache.datasketches.memory
-```
-
-Note that these arguments are not required for cases where memory is allocated on the heap.
+See the [usage instructions](usage-instructions.md) for more details.
### JPMS and Java 8
-Java 8 does not support module declarations and the JPMS module system.
+Java 8 does not support module declarations and the JPMS module system, and no additional
+runtime arguments are necessary.
However, support is retained for Java 8 users by only including the compiled declaration
(`module-info.class`) in the `datasketches-memory` multi-release JAR for Java9 and above.
diff --git a/docs/multi-release-jar.md b/docs/multi-release-jar.md
index 0f6ed4c..470ca8e 100644
--- a/docs/multi-release-jar.md
+++ b/docs/multi-release-jar.md
@@ -19,8 +19,8 @@
# Multi-Release JAR
-The `datasketches-memory` module assembles a JAR for release that consists of multiple
-Java-release-specific versions of class files to coexist in a single archive (the MR-JAR).
+The `datasketches-memory` module assembles a multi-release (MR) JAR for release that consists of
+multiple Java-release-specific versions of compiled class files.
From [JEP-238](https://openjdk.java.net/jeps/238):
@@ -30,7 +30,8 @@ language or API features available in newer releases since it is difficult to ex
platform dependencies, which generally involves reflection, or to distribute different library
artifacts for different platform versions.
-This is specifically the case for the DataSketches Memory component.
+The next case describes the challenge in supporting newer versions of Java for libraries
+such as DataSketches Memory:
> Some libraries and frameworks, furthermore, use internal APIs of the JDK that will be made
inaccessible in Java 9 when module boundaries are strictly enforced. This also creates a
diff --git a/docs/usage-instructions.md b/docs/usage-instructions.md
new file mode 100644
index 0000000..969012b
--- /dev/null
+++ b/docs/usage-instructions.md
@@ -0,0 +1,203 @@
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+
+# Usage Instructions
+
+You may need to supply additional runtime arguments to the JVM depending on how you are using the Datasketches Memory library.
+There are several applicable use cases that are considered:
+
+1) Using the library from a Java 8 application
+2) Using the library with on-heap memory only
+3) Using off-heap memory in a non-modularized Java 9+ application
+4) Using off-heap memory in a modularized Java 9+ application
+
+### 1) Using the library from a Java 8 application
+
+No additional runtime arguments are required.
+
+As an example, consider the following launch script that compiles and runs a simple Java 8 application:
+
+```shell
+ export JAVA_HOME=$JAVA8_HOME
+ export JAVAC=$JAVA_HOME/bin/javac
+ export JAR=$JAVA_HOME/bin/jar
+ export JAVA=$JAVA_HOME/bin/java
+ patha=nomvn-jdk8
+
+ cd $patha
+ echo PWD:$(pwd)
+ echo $JAVA_HOME
+
+ echo "--- CLEAN & COMPILE ---"
+ rm -rf target
+ mkdir target
+ mkdir target/classes
+ mkdir target/test-classes
+
+ $JAVAC -d target/test-classes/ -cp "libs/*" $(find . -name '*.java')
+
+ echo "---- RUN ----"
+ echo PWD:$(pwd)
+
+ $JAVA\
+ -cp target/test-classes:libs/*:src/test/resources/\
+ org.xyz.memory.CheckJava8
+```
+
+### 2) Using the library with on-heap memory only
+
+No additional runtime arguments are required, regardless of whether the library is used from a Java 8 or Java 9+
+application.
+
+As an example, consider the following launch script that compiles and runs a simple Java 9 application that only exclusively
+uses on-heap memory:
+
+```shell
+ export JAVA_HOME=$JAVA9_HOME
+ export JAVAC=$JAVA_HOME/bin/javac
+ export JAR=$JAVA_HOME/bin/jar
+ export JAVA=$JAVA_HOME/bin/java
+ patha=nomvn-nomod-heap-jdk9
+
+ cd $patha
+ echo PWD:$(pwd)
+ echo $JAVA_HOME
+
+ echo "--- CLEAN & COMPILE ---"
+ rm -rf target
+ mkdir target
+ mkdir target/classes
+ mkdir target/test-classes
+
+ $JAVAC -d target/test-classes -cp "mods/*":"libs/*" -p mods $(find . -name '*.java')
+
+ echo "---- RUN ----"
+
+ echo PWD:$(pwd)
+
+ $JAVA\
+ -cp target/test-classes:"mods/*":"libs/*":src/test/resources\
+ org.xyz.memory.CheckJava9plus
+```
+
+### 3) Using off-heap memory in a non-modularized Java 9+ application
+
+The following section applies to applications that are not modularized JPMS applications.
+
+In order to allocate off-heap memory using the library in Java 9 and above, you must provide the
+following runtime arguments to the JVM:
+
+```shell
+ --add-exports java.base/jdk.internal.misc=ALL-UNNAMED\
+ --add-exports java.base/jdk.internal.ref=ALL-UNNAMED\
+ --add-opens java.base/java.nio=ALL-UNNAMED\
+ --add-opens java.base/sun.nio.ch=ALL-UNNAMED\
+```
+
+These arguments expose encapsulated packages in the `java.base` package to the `org.apache.datasketches.memory` module,
+which runs as an UNNAMED module in a non-JPMS (non-modularized) application.
+
+The following launch script compiles and runs a non-modularized Java 9 application:
+
+```shell
+
+ export JAVA_HOME=$JAVA9_HOME
+ export JAVAC=$JAVA_HOME/bin/javac
+ export JAR=$JAVA_HOME/bin/jar
+ export JAVA=$JAVA_HOME/bin/java
+ patha=nomvn-nomod-jdk9
+
+ cd $patha
+ echo PWD:$(pwd)
+ echo $JAVA_HOME
+
+ echo "--- CLEAN & COMPILE ---"
+ rm -rf target
+ mkdir target
+ mkdir target/classes
+ mkdir target/test-classes
+
+ $JAVAC -d target/test-classes -cp "mods/*":"libs/*" -p mods $(find . -name '*.java')
+
+ echo "---- RUN ----"
+
+ echo PWD:$(pwd)
+
+ $JAVA\
+ --add-exports java.base/jdk.internal.misc=ALL-UNNAMED\
+ --add-exports java.base/jdk.internal.ref=ALL-UNNAMED\
+ --add-opens java.base/java.nio=ALL-UNNAMED\
+ --add-opens java.base/sun.nio.ch=ALL-UNNAMED\
+ -cp target/test-classes:"mods/*":"libs/*":src/test/resources\
+ org.xyz.memory.CheckJava9plus
+```
+where the traditional classpath (`-cp`) argument contains all modules, libraries and resources.
+
+Note: `mods` is a local directory containing external modules, and `libs` is a localy directory for external library
+dependencies. No distinction is made between modules and libraries since they are both appended to the classpath.
+
+### 4) Using off-heap memory in a modularized Java 9+ application
+
+The following section applies to modularized JPMS applications.
+
+In order to allocate off-heap memory using the library in Java 9 and above, you must provide the
+following runtime arguments to the JVM:
+
+```shell
+ --add-exports java.base/jdk.internal.misc=org.apache.datasketches.memory\
+ --add-exports java.base/jdk.internal.ref=org.apache.datasketches.memory\
+ --add-opens java.base/java.nio=org.apache.datasketches.memory\
+ --add-opens java.base/sun.nio.ch=org.apache.datasketches.memory\
+```
+
+These arguments expose encapsulated packages in the `java.base` package to the `org.apache.datasketches.memory` module.
+
+The following launch script compiles and runs a modularized Java 9 application:
+
+```shell
+ export JAVA_HOME=$JAVA9_HOME
+ export JAVAC=$JAVA_HOME/bin/javac
+ export JAR=$JAVA_HOME/bin/jar
+ export JAVA=$JAVA_HOME/bin/java
+ patha=nomvn-mod-jdk9
+
+ cd $patha
+ echo PWD:$(pwd)
+ echo $JAVA_HOME
+
+ echo "--- CLEAN & COMPILE ---"
+ rm -rf target
+ mkdir target
+ mkdir target/classes
+ mkdir target/test-classes
+
+ $JAVAC -d target/test-classes -cp "libs/*" -p mods $(find . -name '*.java')
+
+ echo "---- RUN ----"
+ echo PWD:$(pwd)
+
+ $JAVA\
+ --add-opens java.base/java.nio=org.apache.datasketches.memory\
+ --add-opens java.base/sun.nio.ch=org.apache.datasketches.memory\
+ -cp "/libs/*":src/test/resources\
+ -p target/test-classes:mods\
+ -m org.xyz.memory/org.xyz.memory.CheckJava9plus
+```
+where the traditional classpath (`-cp`) argument contains libraries and resources, and the module-path argument (`-p`)
+references all external modules and compiled classes for the current user application, which is itself a module.
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@datasketches.apache.org
For additional commands, e-mail: commits-help@datasketches.apache.org