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:51 UTC
[datasketches-memory] branch minor-doc-fixes created (now 5227ac1)
This is an automated email from the ASF dual-hosted git repository.
leerho pushed a change to branch minor-doc-fixes
in repository https://gitbox.apache.org/repos/asf/datasketches-memory.git.
at 5227ac1 Minor doc fixes.
This branch includes the following new commits:
new 5227ac1 Minor doc fixes.
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.
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@datasketches.apache.org
For additional commands, e-mail: commits-help@datasketches.apache.org
[datasketches-memory] 01/01: Minor doc fixes.
Posted by le...@apache.org.
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