You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@datasketches.apache.org by le...@apache.org on 2021/08/18 18:15:52 UTC
[datasketches-memory] 01/01: Minor doc fixes.
This is an automated email from the ASF dual-hosted git repository.
leerho pushed a commit to branch minor-doc-fixes
in repository https://gitbox.apache.org/repos/asf/datasketches-memory.git
commit 5227ac100d587248a0138fab0afa970e7047d7a8
Author: Lee Rhodes <le...@users.noreply.github.com>
AuthorDate: Wed Aug 18 11:15:25 2021 -0700
Minor doc fixes.
---
docs/maven-toolchains.md | 7 ++++---
docs/module-system.md | 19 +++++++++++--------
docs/usage-instructions.md | 14 +++++++-------
3 files changed, 22 insertions(+), 18 deletions(-)
diff --git a/docs/maven-toolchains.md b/docs/maven-toolchains.md
index 26ad6b1..5fdb58a 100644
--- a/docs/maven-toolchains.md
+++ b/docs/maven-toolchains.md
@@ -39,10 +39,11 @@ version-specific APIs, which require different JDKs to compile correctly.
Your local environment requires toolchain entries for Java 8, 9 and 11 to build this project.
These can be found in a reference `toolchains.xml` template in the `tools` directory.
Any maven commands used during development can be supplemented with:
-`--toolchains tools/toolchains.xml`, without permanently modifying a local
-`~/.m2/toolchains.xml` file (recommended).
+`--toolchains tools/toolchains.xml`, without permanently modifying the local
+`~/.m2/toolchains.xml` file.
-Alternatively, the toolchain template can be copied to your local maven `toolchains.xml`,
+Alternatively, to avoid having to add this extra argument to every Maven command,
+the toolchain template can be copied to your local maven `toolchains.xml`,
e.g. `~/.m2/toolchains.xml`. If there is already a locally configured `toolchains.xml` file,
the requisite entries should be merged into the existing file if they do not already exist.
diff --git a/docs/module-system.md b/docs/module-system.md
index 2991985..c3eabb5 100644
--- a/docs/module-system.md
+++ b/docs/module-system.md
@@ -17,7 +17,7 @@
under the License.
-->
-# Java Platform Module System (JPMS)
+# Java Platform Module System (JPMS) For JDK 9+
The [Java Platform Module System](https://openjdk.java.net/projects/jigsaw/spec/) defines a module
system for the Java Platform. For more documentation on the implementation, see
@@ -63,7 +63,7 @@ module org.apache.datasketches.memory {
```
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,
+external API. The `org.apache.datasketches.memory.internal` package is now inaccessible to the end user,
providing better encapsulation.
### Compiler arguments
@@ -73,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 depends on several internal APIs and therefore requires special
exposition.
For example, in order to compile the `datasketches-memory-java9` submodule, the following compiler
@@ -86,12 +86,15 @@ arguments are added to the Maven compiler plugin in the module's pom.xml file:
</compilerArgs>
```
-### Runtime arguments (off-heap memory only)
+### Runtime arguments (only when allocating off-heap memory)
-When allocating off-heap memory, reflection is used by the datasketches memory library in cases
-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.
+When allocating off-heap memory using `WritableMemory.allocateDirect(...)`,
+reflection is used by the datasketches memory component to access JVM internal class
+fields and methods that do not have `public` visibility. For JDK 9+, the JPMS
+requires that the user add additional JVM run-time arguments (`add-opens...`, which permit this reflection.
+
+Note that if the user has allocated off-heap memory using ByteBuffer.allocateDirect(...),
+the DataSketches memory component can still read and write to this memory without these `add-opens...` arguments.
See the [usage instructions](usage-instructions.md) for more details.
diff --git a/docs/usage-instructions.md b/docs/usage-instructions.md
index 969012b..7783d74 100644
--- a/docs/usage-instructions.md
+++ b/docs/usage-instructions.md
@@ -22,10 +22,10 @@
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
+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
@@ -60,7 +60,7 @@ As an example, consider the following launch script that compiles and runs a sim
org.xyz.memory.CheckJava8
```
-### 2) Using the library with on-heap memory only
+### 2) Using the library with on-heap memory only, or with off-heap memory allocated via ByteBuffer by the user.
No additional runtime arguments are required, regardless of whether the library is used from a Java 8 or Java 9+
application.
@@ -100,7 +100,7 @@ uses on-heap memory:
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
+In order to allocate off-heap memory using the `WritableMemory.allocateDirect(...)` method in Java 9 and above, you must provide the
following runtime arguments to the JVM:
```shell
@@ -156,7 +156,7 @@ dependencies. No distinction is made between modules and libraries since they a
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
+In order to allocate off-heap memory using the `WritableMemory.allocateDirect(...)` method in Java 9 and above, you must provide the
following runtime arguments to the JVM:
```shell
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@datasketches.apache.org
For additional commands, e-mail: commits-help@datasketches.apache.org