This is an automated email from the ASF dual-hosted git repository.
lhotari pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/pulsar-site.git
The following commit(s) were added to refs/heads/main by this push:
new 94691ce24bae Add comment of why optimized Netty direct memory access
is important
94691ce24bae is described below
commit 94691ce24bae5c1bbed03b67848001d9c39d7f61
Author: Lari Hotari <[email protected]>
AuthorDate: Thu Oct 24 09:45:58 2024 +0300
Add comment of why optimized Netty direct memory access is important
---
docs/client-libraries-java-setup.md | 1 +
docs/client-libraries-java.md | 6 +++++
.../version-3.0.x/client-libraries-java-setup.md | 27 +++++++++++++++++++++-
.../version-3.0.x/client-libraries-java.md | 10 ++++++--
.../version-3.2.x/client-libraries-java-setup.md | 1 +
.../version-3.2.x/client-libraries-java.md | 8 ++++++-
.../version-3.3.x/client-libraries-java-setup.md | 1 +
.../version-3.3.x/client-libraries-java.md | 8 ++++++-
.../version-4.0.x/client-libraries-java-setup.md | 1 +
.../version-4.0.x/client-libraries-java.md | 6 +++++
10 files changed, 64 insertions(+), 5 deletions(-)
diff --git a/docs/client-libraries-java-setup.md
b/docs/client-libraries-java-setup.md
index 09b4b8914697..539630d8979e 100644
--- a/docs/client-libraries-java-setup.md
+++ b/docs/client-libraries-java-setup.md
@@ -174,6 +174,7 @@ By default Java applications have a limit for direct memory
allocations. The all
The Pulsar Java client uses [Netty](https://netty.io/) under the hood and uses
Netty direct buffers for data transport.
Netty has a feature that allows optimized direct memory buffer access. This
feature enables Netty to use low level APIs such as `sun.misc.Unsafe` for
direct memory operations, which provides faster allocation and deallocation of
direct buffers.
+The faster deallocation can help avoid direct memory exhaustion and
`java.lang.OutOfMemoryError: Direct buffer memory` errors. These errors can
occur when the Netty memory pool and memory allocator cannot release memory
back to the operating system quickly enough.
To enable this feature in Java clients since Java 11, you need to add the
following JVM options to the application that uses the Java client:
diff --git a/docs/client-libraries-java.md b/docs/client-libraries-java.md
index c71740334b5c..c0793e0db08e 100644
--- a/docs/client-libraries-java.md
+++ b/docs/client-libraries-java.md
@@ -12,6 +12,12 @@ You can use a Pulsar Java client to create Pulsar
[producers](concepts-clients.m
2. [Initialize a Java client](client-libraries-java-initialize.md)
3. [Use a Java client](client-libraries-java-use.md)
+:::note
+
+Please refer to [Java client Performance
considerations](client-libraries-java-setup.md#java-client-performance) for
more information on how to improve the performance of the Java client and tune
the Java JVM options to avoid `java.lang.OutOfMemoryError: Direct buffer
memory` errors in high-throughput applications.
+
+:::
+
## What's next?
- [Work with clients](client-libraries-clients.md)
diff --git a/versioned_docs/version-3.0.x/client-libraries-java-setup.md
b/versioned_docs/version-3.0.x/client-libraries-java-setup.md
index c846efe26766..0ab4c499b562 100644
--- a/versioned_docs/version-3.0.x/client-libraries-java-setup.md
+++ b/versioned_docs/version-3.0.x/client-libraries-java-setup.md
@@ -63,4 +63,29 @@ If you use [mTLS](security-tls-authentication.md)
authentication, add `+ssl` in
```http
pulsar+ssl://pulsar.us-west.example.com:6651
-```
\ No newline at end of file
+```
+
+## Java client Performance considerations {#java-client-performance}
+
+### Increasing the memory limit
+
+For high-throughput applications, you can increase the amount of memory with
the Java client builder's [`memoryLimit` configuration
option](https://pulsar.apache.org/api/client/4.0.x/org/apache/pulsar/client/api/ClientBuilder.html#memoryLimit(long,org.apache.pulsar.client.api.SizeUnit)).
The default limit is 64MB which is usually too low for high-throughput
applications.
+
+By default Java applications have a limit for direct memory allocations. The
allocations are limited by the `-XX:MaxDirectMemorySize` JVM option. In many
JVM implementations, this defaults to the maximum heap size unless explicitly
set. Allocations happen outside of the Java heap.
+
+### Enabling optimized Netty direct memory buffer access
+
+The Pulsar Java client uses [Netty](https://netty.io/) under the hood and uses
Netty direct buffers for data transport.
+
+Netty has a feature that allows optimized direct memory buffer access. This
feature enables Netty to use low level APIs such as `sun.misc.Unsafe` for
direct memory operations, which provides faster allocation and deallocation of
direct buffers.
+The faster deallocation can help avoid direct memory exhaustion and
`java.lang.OutOfMemoryError: Direct buffer memory` errors. These errors can
occur when the Netty memory pool and memory allocator cannot release memory
back to the operating system quickly enough.
+
+To enable this feature in Java clients since Java 11, you need to add the
following JVM options to the application that uses the Java client:
+
+- `--add-opens java.base/java.nio=ALL-UNNAMED`
+- `--add-opens java.base/jdk.internal.misc=ALL-UNNAMED`
+
+In addition, you need to add one of the following JVM options:
+
+- `-Dorg.apache.pulsar.shade.io.netty.tryReflectionSetAccessible=true` for the
default shaded Pulsar client
+- `-Dio.netty.tryReflectionSetAccessible=true` for the unshaded "original"
Pulsar client
\ No newline at end of file
diff --git a/versioned_docs/version-3.0.x/client-libraries-java.md
b/versioned_docs/version-3.0.x/client-libraries-java.md
index 549e018f1bd6..c0793e0db08e 100644
--- a/versioned_docs/version-3.0.x/client-libraries-java.md
+++ b/versioned_docs/version-3.0.x/client-libraries-java.md
@@ -12,6 +12,12 @@ You can use a Pulsar Java client to create Pulsar
[producers](concepts-clients.m
2. [Initialize a Java client](client-libraries-java-initialize.md)
3. [Use a Java client](client-libraries-java-use.md)
+:::note
+
+Please refer to [Java client Performance
considerations](client-libraries-java-setup.md#java-client-performance) for
more information on how to improve the performance of the Java client and tune
the Java JVM options to avoid `java.lang.OutOfMemoryError: Direct buffer
memory` errors in high-throughput applications.
+
+:::
+
## What's next?
- [Work with clients](client-libraries-clients.md)
@@ -36,5 +42,5 @@ Package | Description | Maven Artifact
#### More reference
- [Java client
configurations](pathname:///reference/#/@pulsar:version_reference@/client/)
-- [Release notes](pathname:///release-notes/client-java)
-- [Client feature
matrix](https://docs.google.com/spreadsheets/d/1YHYTkIXR8-Ql103u-IMI18TXLlGStK8uJjDsOOA0T20/edit#gid=1784579914)
\ No newline at end of file
+- [Release notes](/release-notes/client-java)
+- [Client feature matrix](/client-feature-matrix/)
diff --git a/versioned_docs/version-3.2.x/client-libraries-java-setup.md
b/versioned_docs/version-3.2.x/client-libraries-java-setup.md
index 09b4b8914697..539630d8979e 100644
--- a/versioned_docs/version-3.2.x/client-libraries-java-setup.md
+++ b/versioned_docs/version-3.2.x/client-libraries-java-setup.md
@@ -174,6 +174,7 @@ By default Java applications have a limit for direct memory
allocations. The all
The Pulsar Java client uses [Netty](https://netty.io/) under the hood and uses
Netty direct buffers for data transport.
Netty has a feature that allows optimized direct memory buffer access. This
feature enables Netty to use low level APIs such as `sun.misc.Unsafe` for
direct memory operations, which provides faster allocation and deallocation of
direct buffers.
+The faster deallocation can help avoid direct memory exhaustion and
`java.lang.OutOfMemoryError: Direct buffer memory` errors. These errors can
occur when the Netty memory pool and memory allocator cannot release memory
back to the operating system quickly enough.
To enable this feature in Java clients since Java 11, you need to add the
following JVM options to the application that uses the Java client:
diff --git a/versioned_docs/version-3.2.x/client-libraries-java.md
b/versioned_docs/version-3.2.x/client-libraries-java.md
index f536f5273b10..c0793e0db08e 100644
--- a/versioned_docs/version-3.2.x/client-libraries-java.md
+++ b/versioned_docs/version-3.2.x/client-libraries-java.md
@@ -12,6 +12,12 @@ You can use a Pulsar Java client to create Pulsar
[producers](concepts-clients.m
2. [Initialize a Java client](client-libraries-java-initialize.md)
3. [Use a Java client](client-libraries-java-use.md)
+:::note
+
+Please refer to [Java client Performance
considerations](client-libraries-java-setup.md#java-client-performance) for
more information on how to improve the performance of the Java client and tune
the Java JVM options to avoid `java.lang.OutOfMemoryError: Direct buffer
memory` errors in high-throughput applications.
+
+:::
+
## What's next?
- [Work with clients](client-libraries-clients.md)
@@ -37,4 +43,4 @@ Package | Description | Maven Artifact
- [Java client
configurations](pathname:///reference/#/@pulsar:version_reference@/client/)
- [Release notes](/release-notes/client-java)
-- [Client feature matrix](/client-feature-matrix/)
\ No newline at end of file
+- [Client feature matrix](/client-feature-matrix/)
diff --git a/versioned_docs/version-3.3.x/client-libraries-java-setup.md
b/versioned_docs/version-3.3.x/client-libraries-java-setup.md
index 09b4b8914697..539630d8979e 100644
--- a/versioned_docs/version-3.3.x/client-libraries-java-setup.md
+++ b/versioned_docs/version-3.3.x/client-libraries-java-setup.md
@@ -174,6 +174,7 @@ By default Java applications have a limit for direct memory
allocations. The all
The Pulsar Java client uses [Netty](https://netty.io/) under the hood and uses
Netty direct buffers for data transport.
Netty has a feature that allows optimized direct memory buffer access. This
feature enables Netty to use low level APIs such as `sun.misc.Unsafe` for
direct memory operations, which provides faster allocation and deallocation of
direct buffers.
+The faster deallocation can help avoid direct memory exhaustion and
`java.lang.OutOfMemoryError: Direct buffer memory` errors. These errors can
occur when the Netty memory pool and memory allocator cannot release memory
back to the operating system quickly enough.
To enable this feature in Java clients since Java 11, you need to add the
following JVM options to the application that uses the Java client:
diff --git a/versioned_docs/version-3.3.x/client-libraries-java.md
b/versioned_docs/version-3.3.x/client-libraries-java.md
index f536f5273b10..c0793e0db08e 100644
--- a/versioned_docs/version-3.3.x/client-libraries-java.md
+++ b/versioned_docs/version-3.3.x/client-libraries-java.md
@@ -12,6 +12,12 @@ You can use a Pulsar Java client to create Pulsar
[producers](concepts-clients.m
2. [Initialize a Java client](client-libraries-java-initialize.md)
3. [Use a Java client](client-libraries-java-use.md)
+:::note
+
+Please refer to [Java client Performance
considerations](client-libraries-java-setup.md#java-client-performance) for
more information on how to improve the performance of the Java client and tune
the Java JVM options to avoid `java.lang.OutOfMemoryError: Direct buffer
memory` errors in high-throughput applications.
+
+:::
+
## What's next?
- [Work with clients](client-libraries-clients.md)
@@ -37,4 +43,4 @@ Package | Description | Maven Artifact
- [Java client
configurations](pathname:///reference/#/@pulsar:version_reference@/client/)
- [Release notes](/release-notes/client-java)
-- [Client feature matrix](/client-feature-matrix/)
\ No newline at end of file
+- [Client feature matrix](/client-feature-matrix/)
diff --git a/versioned_docs/version-4.0.x/client-libraries-java-setup.md
b/versioned_docs/version-4.0.x/client-libraries-java-setup.md
index 09b4b8914697..539630d8979e 100644
--- a/versioned_docs/version-4.0.x/client-libraries-java-setup.md
+++ b/versioned_docs/version-4.0.x/client-libraries-java-setup.md
@@ -174,6 +174,7 @@ By default Java applications have a limit for direct memory
allocations. The all
The Pulsar Java client uses [Netty](https://netty.io/) under the hood and uses
Netty direct buffers for data transport.
Netty has a feature that allows optimized direct memory buffer access. This
feature enables Netty to use low level APIs such as `sun.misc.Unsafe` for
direct memory operations, which provides faster allocation and deallocation of
direct buffers.
+The faster deallocation can help avoid direct memory exhaustion and
`java.lang.OutOfMemoryError: Direct buffer memory` errors. These errors can
occur when the Netty memory pool and memory allocator cannot release memory
back to the operating system quickly enough.
To enable this feature in Java clients since Java 11, you need to add the
following JVM options to the application that uses the Java client:
diff --git a/versioned_docs/version-4.0.x/client-libraries-java.md
b/versioned_docs/version-4.0.x/client-libraries-java.md
index c71740334b5c..c0793e0db08e 100644
--- a/versioned_docs/version-4.0.x/client-libraries-java.md
+++ b/versioned_docs/version-4.0.x/client-libraries-java.md
@@ -12,6 +12,12 @@ You can use a Pulsar Java client to create Pulsar
[producers](concepts-clients.m
2. [Initialize a Java client](client-libraries-java-initialize.md)
3. [Use a Java client](client-libraries-java-use.md)
+:::note
+
+Please refer to [Java client Performance
considerations](client-libraries-java-setup.md#java-client-performance) for
more information on how to improve the performance of the Java client and tune
the Java JVM options to avoid `java.lang.OutOfMemoryError: Direct buffer
memory` errors in high-throughput applications.
+
+:::
+
## What's next?
- [Work with clients](client-libraries-clients.md)
