@@ -236,6 +236,28 @@ before submitting the next batch.
236236See the [ Acquisition queue] section of the Pooling section in the manual for explanation of how the driver enqueues
237237requests 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