Netty Message RefCount

ByteBuf is always reference counted

To control the life cycle of a ByteBuf in a more predictable way, Netty does not rely on the garbage collector anymore but employs an explicit reference counter. Here's the basic rule:

• When a buffer is allocated, its initial reference count is 1.
• If the reference count of the buffer is decreased to 0, it is deallocated or returned to the pool it originated from.
• The following attempts trigger an IllegalReferenceCountException:
  • Accessing a buffer whose reference count is 0,
  • Decreasing the reference count to a negative value, or
  • Increasing the reference count beyond Integer.MAX_VALUE.
• Derived buffers (e.g. slices and duplicates) and swapped buffers (i.e. little endian buffers) share the reference count with the buffer it was derived from. Note the the reference count does not change when a derived buffer is created.

When a ByteBuf is used in a ChannelPipeline, there are additional rules you need to keep in mind:

• Each inbound (a.k.a. upstream) handler in a pipeline has to release the received messages. Netty does not release them automatically for you.
  • Note that codec framework does release the messages automatically and a user has to increase the reference count if he or she wants to pass a message as-is to the next handler.
• When an outbound (a.k.a. downstream) message reaches at the beginning of the pipeline, Netty will release it after writing it out.

Automatic buffer leak detection

Although reference counting is very powerful, it is also error-prone. To help a user find where he or she forgot to release the buffers, the leak detector logs the stack trace of the location where the leaked buffer was allocated automatically.

Because the leak detector relies on PhantomReference and obtaining a stack trace is a very expensive operation, it samples approximately 1% of allocations only. Therefore, it's a good idea to run the application for a reasonably long time to find all possible leaks.

Once all leaks are found and fixed. You can turn this feature off to remove its runtime overhead completely by specifying the -Dio.netty.noResourceLeakDetection JVM option.