Skip navigation

Native transports

Did you know this page is automatically generated from a Github Wiki page? You can improve it by yourself here!

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.

Using the native transports

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

Using the Linux native transport

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

  • NioEventLoopGroupEpollEventLoopGroup
  • NioEventLoopEpollEventLoop
  • NioServerSocketChannelEpollServerSocketChannel
  • NioSocketChannelEpollSocketChannel

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"

Using the MacOS/BSD native transport

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

  • NioEventLoopGroupKQueueEventLoopGroup
  • NioEventLoopKQueueEventLoop
  • NioServerSocketChannelKQueueServerSocketChannel
  • NioSocketChannelKQueueSocketChannel

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"

Building the native transports

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.

Building the Linux native transport

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

Building the MacOS/BSD native transport

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
Last retrieved on 09-Oct-2024