Native transports

Netty provides the following platform specific JNI transports:

• Linux (since 4.0.16)
• MacOS/BSD (since 4.1.11)

These JNI transports add features specific to a particular platform, generate less garbage, and generally improve performance when compared to the NIO based transport.

Note that you must specify the proper classifier for the dependency to ensure that the corresponding native libraries are included.

Because the native transport is compatible with the NIO transport, you can just do the following search-and-replace:

• NioEventLoopGroup → EpollEventLoopGroup
• NioEventLoop → EpollEventLoop
• NioServerSocketChannel → EpollServerSocketChannel
• NioSocketChannel → EpollSocketChannel

Because the native transport is not part of the Netty core, you need to pull the netty-transport-native-epoll as a dependency in your Maven pom.xml, or equivalent for your build system:

  <dependencies>
    <dependency>
      <groupId>io.netty</groupId>
      <artifactId>netty-transport-native-epoll</artifactId>
      <version>${project.version}</version>
      <classifier>linux-x86_64</classifier>
    </dependency>
    ...
  </dependencies>

In the above, the classifier is linux-x86_64, which means the native binaries included in the dependency are compiled for Linux, running on 64-bit x86 CPUs. Other CPU architectures, and some specific Linux distributions, will need different classifiers.

Note: The official Linux builds are all linked against GLIBC. This means operating systems that use Musl as their libc implementation are not supported by the official builds of the Netty native transports. If you wish to use the Netty native transports on unsupported CPU architectures or libc implementations, you will need to make your own build. See below for how to do that.

For using the native transport in a sbt project, please add line below to your libraryDependencies:

"io.netty" % "netty-transport-native-epoll" % "${project.version}" classifier "linux-x86_64"

Because the native transport is compatible with the NIO transport, you can just do the following search-and-replace:

• NioEventLoopGroup → KQueueEventLoopGroup
• NioEventLoop → KQueueEventLoop
• NioServerSocketChannel → KQueueServerSocketChannel
• NioSocketChannel → KQueueSocketChannel

Because the native transport is not part of the Netty core, you need to pull the netty-transport-native-kqueue as a dependency in your Maven pom.xml:

  <dependencies>
    <dependency>
      <groupId>io.netty</groupId>
      <artifactId>netty-transport-native-kqueue</artifactId>
      <version>${project.version}</version>
      <classifier>osx-x86_64</classifier>
    </dependency>
    ...
  </dependencies>

For using the native transport in a sbt project, please add line below to your libraryDependencies:

"io.netty" % "netty-transport-native-kqueue" % "${project.version}" classifier "osx-x86_64"

If you already have the JAR file of the native transport, you should not need to build the native transport by yourself because the JAR file already contains the necessary shared library files (e.g. .so, .dll, .dynlib) and they will be loaded automatically.

To build the native transport, you need to use Linux with 64-bit kernel 2.6 or higher. Please also install the required tools and libraries:

# RHEL/CentOS/Fedora:
sudo yum install autoconf automake libtool make tar \
                 glibc-devel \
                 libgcc.i686 glibc-devel.i686
# Debian/Ubuntu:
sudo apt-get install autoconf automake libtool make tar \
                     gcc

To build the native transport, you need to use MacOS 10.12 or higher. Please also install the required tools and libraries:

brew install autoconf automake libtool