Home

Needle provides a feature rich, unopinionated interface to core affinity (aka "CPU pinning").

Built on top of JNA, this library utilizes the underlying OS scheduling facilities in order to assign selected threads to utilize specific CPU cores.

Motivation

This library was written in order to address the needs of HFT platforms, similar to other affinity frameworks such as:

• Java-Thread-Affinity by OpenHFT
• CoralThreads by CorrelBlocks

Differing from the aforementioned libraries, needle focuses on flexibility and extensibility, aiming to help the developer better divide compute resources between critical and non-critical application paths, with ease of use and integration in mind.

Getting Started

Just add the following maven (artifacts are hosted on maven central), and you're all set to start pinning!

<dependency>
    <groupId>org.sheinbergon</groupId>
    <!-- also retrieves the needle-core dependency  -->
    <artifactId>needle-concurrent</artifactId>
    <version>0.3.0-RELEASE</version>
    <type>jar</type>
</dependency>

Or if you're working with gradle:

 api 'org.sheinbergon:needle-concurrent:0.3.0-RELEASE'

Feature Overview

• Linux/Windows OS support
• Affinity aware drop-in replacements for a java thread, providing external control over a thread's affinity.
• Minimal integration affinity control by calling affinity methods from within the execution scope of a standard thread.
• Java concurrent extensions (affinity thread factories, thread-pool, scheduled executors, and fork-join pool implementation)
• Kotlin support (including coroutines pinned dispatchers)
• Process wide, Thread-level Core shielding via javaagent instrumentation

On the Roadmap

• Java Fork-Join Pool drop-in replacement
• Kotlin coroutine dispatcher extension
• Affinity setting/shielding for uncontrolled threads, launched by either the JVM or 3rd party libraries
• Detailed Wiki
• Affinity lock support
• Web-based/API affinity reporting/control
• Akka integration extension
• Vert.X integration extension

Probably not on the roadmap

• MacOS support
• RxJava integration extension