Skip to content

Commit 07d81db

Browse files
tolbertamolim7t
authored andcommitted
JAVA-1607: Add FAQ entry for netty-transport-native-epoll
1 parent a0d8b56 commit 07d81db

2 files changed

Lines changed: 23 additions & 0 deletions

File tree

changelog/README.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@
88
- [improvement] JAVA-1500: Add a metric to report number of in-flight requests.
99
- [bug] JAVA-1438: QueryBuilder check for empty orderings.
1010
- [improvement] JAVA-1490: Allow zero delay for speculative executions.
11+
- [documentation] JAVA-1607: Add FAQ entry for netty-transport-native-epoll.
1112

1213

1314
### 3.3.0

faq/README.md

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -236,6 +236,28 @@ before submitting the next batch.
236236
See the [Acquisition queue] section of the Pooling section in the manual for explanation of how the driver enqueues
237237
requests when connections are over-utilized.
238238

239+
### What is Netty's native epoll transport and how do I enable or disable it?
240+
241+
Netty provides [native transport libraries](http://netty.io/wiki/native-transports.html) which generally generate less
242+
garbage and improve performance when compared to the default NIO-based transport.
243+
By default if the driver detects the `netty-transport-native-epoll` library in its classpath it will attempt to use
244+
[`EpollEventLoopGroup`](https://netty.io/4.0/api/io/netty/channel/epoll/EpollEventLoopGroup.html) for its underlying
245+
event loop.
246+
247+
In the usual case this works fine in linux environments. On the other hand, many users have run into compatibility
248+
issues when the version of `netty-transport-native-epoll` is not compatible with a version of Netty in an application's
249+
classpath. One such case is where an application depends on a version of `netty-all` that is different than the
250+
version of `netty-handler` that the driver depends on. In such a case, a user may encounter an exception such as the
251+
one described in [JAVA-1535](https://datastax-oss.atlassian.net/browse/JAVA-1535).
252+
253+
While the epoll transport may in general improve performance, we expect the improvement to be marginal for a lot of use
254+
cases. Therefore, if you don't want `netty-transport-native-epoll` to be used by the driver even if the library is
255+
present in an application's classpath, the most direct way to disable this is to provide the system property value
256+
`-Dcom.datastax.driver.FORCE_NIO=true` to your application to force the use of the default Netty NIO-based event loop.
257+
If properly used, the following log message will be logged at INFO on startup:
258+
259+
> Found Netty's native epoll transport in the classpath, but NIO was forced through the FORCE_NIO system property.
260+
239261
[Blobs.java]: https://github.com/datastax/java-driver/tree/3.3.0/driver-examples/src/main/java/com/datastax/driver/examples/datatypes/Blobs.java
240262
[CASSANDRA-7304]: https://issues.apache.org/jira/browse/CASSANDRA-7304
241263
[Parameters and Binding]: ../manual/statements/prepared/#parameters-and-binding

0 commit comments

Comments
 (0)