Core Functionality

This section of the wiki covers core concepts and functionality.

These are the foundations on which the entire needle suite of libraries and modules are built upon. Taking the time to familiarize yourself them will help you make the most out of this library while avoiding operational errors.

Affinity Descriptor

Simply put, an AffinityDescriptor contains core affinity specifications. It has two factory methods you can choose from

Textual specification

var descriptor = AffinityDescriptor.from("0-2,4");

Binary mask

var descriptor = AffinityDescriptor.from(23);

Notes

• The above two affinity descriptors are effectually identical: "0-2,4" implies cores 1,2,3 and 5 (the core count starts at 0) while 15, which is 10111 in binary, refers to the same core range exactly.
• Using either AffinityDescriptor.from("") or AffinityDescriptor.from(0) will result in a 'no affinity' (empty) descriptor. This is useful for scenarios where affinity settings are irrelevant or undesired (for example, when running tests)

Pinned Thread

PinnedThread extends upon a standard JVM Thread by adding affinity awareness.

For maximum flexibility, a PinnedThread can be started with or without an initial affinity, as various constructors exist:

Unlike traditional affinity solutions, one of the key strengths of the PinnedThread is its ability to alter the thread's affinity setting externally, beyond its inception!

We can also inquire about a PinnedThread current affinity settings.

The only requirement is for thread to be started before trying to access affinity related functionality. Failure in doing so will result in an error

Extending a PinnedThread is also viable, if your design works that way, though it requires additional attention to affinity setting initialization.

Minimal Integration

In scenarios where it's undesirable or impossible to replace Thread implementations with PinnedThread, you can apply affinity setting from within the run() method in the following way:

// Put the affinity setting inside the Runnable
Runnable runnable = () -> {
    var descriptor = AffinityDescriptor.from("0-1,3");
    Needle.affinity(descriptor);

    // Put the rest of your code here
};

// Create a thread and start it
Thread thread = new Thread(runnable);
thread.start();