Netty mimalloc allocator

A high-performance Java port of the mimalloc allocator, tailored for Netty.

---

🎯 Key Features

• Mimalloc Powered: Leverages mimalloc's advanced allocation strategies (free lists, local shards).
• Tailored for Netty: Specifically designed to handle Netty's ByteBuf allocation with minimal overhead.
• High Throughput: Optimized for multi-threaded network environments to ensure high and stable performance.
• Virtual-Threads Friendly: Optimized for Project Loom, preventing the memory explosion typically caused by massive ThreadLocal usage in virtual thread scenarios.

---

📮 Requirements

Requirement	Minimum Version
Java (JDK)	1.8 or higher
Netty	4.2.10.Final or newer

---

📚 How to use

1. Maven dependencies:

Add the following dependencies to your pom.xml:

    <dependencies>
        <dependency>
            <groupId>io.github.neoionet</groupId>
            <artifactId>mimalloc</artifactId>
            <version>1.2.1.Final</version>
        </dependency>
        <dependency>
            <groupId>io.netty</groupId>
            <artifactId>netty-common</artifactId>
            <version>4.2.17.Final</version>
        </dependency>
        <dependency>
            <groupId>io.netty</groupId>
            <artifactId>netty-buffer</artifactId>
            <version>4.2.17.Final</version>
        </dependency>
    </dependencies>

If you want to use the mimalloc allocator within your server or client transport, ensure the netty-transport dependency is included in your project as well:

    <dependencies>
       <dependency>
            <groupId>io.netty</groupId>
            <artifactId>netty-transport</artifactId>
            <version>4.2.17.Final</version>
        </dependency>
    </dependencies>

2. Quick start

2.1. Initialize Allocator:

// Create an instance of the mimalloc-based allocator.
ByteBufAllocator miMallocAllocator = new MiByteBufAllocator();

2.2. Simple allocation:

ByteBuf buf = miMallocAllocator.directBuffer();
buf.writeLong(123);
System.out.println(buf.readLong()); // print 123.
buf.release();

2.3. Apply to Server:

ServerBootstrap b = new ServerBootstrap();
b.group(bossGroup, workerGroup)
 .channel(NioServerSocketChannel.class)
 .option(ChannelOption.ALLOCATOR, miMallocAllocator) // Set the mimalloc allocator.
 .childOption(ChannelOption.ALLOCATOR, miMallocAllocator) // Set the mimalloc allocator for child.
 ...

2.4. Apply to Client:

Bootstrap b = new Bootstrap();
b.group(group)
 .channel(NioSocketChannel.class)
 .option(ChannelOption.ALLOCATOR, miMallocAllocator) // Set the mimalloc allocator.
 ...

---

🚀 Benchmark

• Report
• Specification

---

🔧 Configuration

1. Global level configuration:

• -Dio.github.neoionet.allocator.mimalloc.heap.strategy

  • Allowed Values(case-insensitive): auto, tl, shared
  • Description: Determines the heap strategy.
  • • auto: EventLoop threads use thread-local heaps, non-EventLoop threads use shared heaps.
  • • tl: Force all threads to use thread-local heaps. NOTE: If you forcefully use tl for non-eventLoop thread, it will not do automatically cleanup when the thread exits.
  • • shared: Force all threads to use shared heaps.
  • Default value: auto

• -Dio.github.neoionet.allocator.mimalloc.page.search.strategy

  • Allowed Values(case-insensitive): best, first
  • Description: Determines the page search strategy.
  • • best stands for best-fit.
  • • first stands for first-fit.
  • Default value: best

• -Dio.github.neoionet.allocator.mimalloc.segment.size.mib

  • Allowed Values: 4, 8, 16, 32
  • Description: Sets the segment size in MiB.
  • Default value: 4

• -Dio.github.neoionet.allocator.mimalloc.maxSharedHeaps

  • Description: Sets the max shared heaps count.
  • Default value: NettyRuntime.availableProcessors() * 4

2. Instance level configuration, which can override the global configuration:

        ByteBufAllocator allocator = MiByteBufAllocator
                                         .builder()
                                         .heapStrategy(MiMallocOption.HeapStrategy.AUTO)
                                         .pageSearchStrategy(MiMallocOption.PageSearchStrategy.BEST)
                                         .segmentSizeInMiB(4)
                                         .maxSharedHeaps(16)
                                         .build();

⭐ Acknowledgments

This project would not be possible without the following open-source works:

• mimalloc - A compact general purpose allocator with excellent performance.
• Netty - An event-driven asynchronous network application framework.

---