org.mentaaffinity
Class Affinity

java.lang.Object
  org.mentaaffinity.Affinity

public class Affinity
extends Object

The main class to set and control many different affinity strategies.

Author:

Sergio Oliveira Jr.

Constructor Summary

Affinity()

Method Summary

static void	bind() This method actually makes the system call to set the thread affinity.
static Core	bindToAnyFreeCore(int chipId, Thread t) Same thing as bindToAnyFreeCore(Thread t) except that you provide the chip from where to get a core.
static Core	bindToAnyFreeCore(Thread t) Looks for a core that has no threads running and bound this thread to it.
static Processor	bindToAnyFreeProcessor(int chipId, Thread t) Choose the first free logical processor available in that chip and bind the thread to it.
static Processor	bindToAnyFreeProcessor(Thread t) Choose the first free logical processor available and bind to this thread.
static void	bindToDifferentChips(int chipId1, Thread t1, int chipId2, Thread t2) Bind the threads to the provided physical processors.
static void	bindToDifferentChips(Thread t1, Thread t2) Make sure that both threads are bound to separate physical processors.
static void	bindToDifferentCores(int chipId, Thread t1, Thread t2) Same thing as bindToDifferentCores(Thread t1, Thread t2) except that you can provide the physical processor.
static void	bindToDifferentCores(Thread t1, Thread t2) Make sure both threads will NOT be bound to the same core.
static void	bindToProcessor(int procId, Thread t) Bind the thread to a single logical processor.
static void	bindToSameCore(int chipId, Thread t1, Thread t2) Same thing as bindToSameCore(Thread t1, Thread t2) except that you can provide the physical processor.
static void	bindToSameCore(Thread t1, Thread t2) Finds a free core and bind both threads to both of its logical processors.
static void	init() Init MentaAffinity by loading the /proc/cpuinfo file.
static boolean	isAvailable() Checks if MentaAffinity is available for your JVM.
static void	printSituation() Prints to System.out a nice outlook of the logical processors situation.
static void	setEnable(boolean flag) By default affinity is enabled but you can turn it off if you want to, for example if you are running in a platform other than Linux.
static void	unbind() This method must be called when the thread is about to die.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Affinity

public Affinity()

Method Detail

setEnable

public static void setEnable(boolean flag)

By default affinity is enabled but you can turn it off if you want to, for example if you are running in a platform other than Linux. The effect of turning it off is that no affinity will be set for any thread, in other words, bind and unbind will be ignored.

Parameters:

flag - true to enable

isAvailable

public static final boolean isAvailable()

Checks if MentaAffinity is available for your JVM. MentaAffinity can only work if JNA is available.

Returns:

true if MentaAffinity is available

init

public static void init()

Init MentaAffinity by loading the /proc/cpuinfo file.

bindToProcessor

public static void bindToProcessor(int procId,
                                   Thread t)

Bind the thread to a single logical processor.

Parameters:

procId - the id of the processor (starts at 0).

t - the thread to bind

Throws:

AffinityException - if cannot bind to this processor

bindToAnyFreeProcessor

public static Processor bindToAnyFreeProcessor(Thread t)

Choose the first free logical processor available and bind to this thread.

Parameters:

t - the thread to bind

Returns:

the processor to where the thread was bound

Throws:

AffinityException - if no free processor was found or if there was a problem binding

bindToAnyFreeProcessor

public static Processor bindToAnyFreeProcessor(int chipId,
                                               Thread t)

Choose the first free logical processor available in that chip and bind the thread to it.

Parameters:

chipId - the physical processor we want to bind to

t - the thread we want to bind

Returns:

the processor that this thread was bound to

Throws:

AffinityException - if it wasn't possible to bind by any reason

bindToAnyFreeCore

public static Core bindToAnyFreeCore(Thread t)

Looks for a core that has no threads running and bound this thread to it. This is very useful for chips with hyper-threading when you want to isolate a single thread in the WHOLE core so there is nobody else competing for the L1 cache in the other logical processor. MentaAffinity will mark the other logical processor as idle until the thread unbinds from the core.

Parameters:

t - the thread to bind

Returns:

the core to where this thread was bound

Throws:

AffinityException - if it wasn't possible to bind by any reason

bindToAnyFreeCore

public static Core bindToAnyFreeCore(int chipId,
                                     Thread t)

Same thing as bindToAnyFreeCore(Thread t) except that you provide the chip from where to get a core. Useful for architectures with more than one physical processor.

Parameters:

chipId - the physical processor

t - the thread to bind

Returns:

the core to where the thread was bound

Throws:

AffinityException - if it wasn't possible to bind by any reason

bindToSameCore

public static void bindToSameCore(Thread t1,
                                  Thread t2)

Finds a free core and bind both threads to both of its logical processors. Of course if the chip does not support hyper-threading this will throw an exception.

Parameters:

t1 - the first thread to bind

t2 - the seconds thread to bind

Throws:

AffinityException - if it wasn't possible to bind by any reason

bindToSameCore

public static void bindToSameCore(int chipId,
                                  Thread t1,
                                  Thread t2)

Same thing as bindToSameCore(Thread t1, Thread t2) except that you can provide the physical processor. Useful for machines with more than one physical processor.

Parameters:

chipId - the physical processor

t1 - the first thread to bind

t2 - the second thread to bind

Throws:

AffinityException - if it wasn't possible to bind by any reason

bindToDifferentCores

public static void bindToDifferentCores(Thread t1,
                                        Thread t2)

Make sure both threads will NOT be bound to the same core. Note that they will still be in the same chip. If you want them to be in separate chips use the bindToDifferentChips method.

Parameters:

t1 - the first thread

t2 - the second thread

Throws:

AffinityException - if it wasn't possible to bind by any reason

bindToDifferentCores

public static void bindToDifferentCores(int chipId,
                                        Thread t1,
                                        Thread t2)

Same thing as bindToDifferentCores(Thread t1, Thread t2) except that you can provide the physical processor. Useful if the machine has more than one physical processor.

Parameters:

chipId - the physical processor

t1 - the first thread

t2 - the second thread

Throws:

AffinityException - if it wasn't possible to bind by any reason

bindToDifferentChips

public static void bindToDifferentChips(Thread t1,
                                        Thread t2)

Make sure that both threads are bound to separate physical processors.

Parameters:

t1 - the first thread

t2 - the second thread

Throws:

AffinityException - if it wasn't possible to bind by any reason

bindToDifferentChips

public static void bindToDifferentChips(int chipId1,
                                        Thread t1,
                                        int chipId2,
                                        Thread t2)

Bind the threads to the provided physical processors. Useful if you have a machine with more than 2 physical processors.

Parameters:

chipId1 - the chip to bind the first thread

t1 - the first thread

chipId2 - the chip to bind the second thread

t2 - the second thread

Throws:

AffinityException - if it wasn't possible to bind by any reason

bind

public static final void bind()

This method actually makes the system call to set the thread affinity. You must call this method from inside your thread, in other words, from inside its run method. If MentaAffinity is not available or disabled then this method is ignored.

Throws:

AffinityException - if it wasn't possible to bind by any reason

unbind

public static final void unbind()

This method must be called when the thread is about to die. This does not make any system call since the thread is dying anyways and there is no need to change any affinity for it. However this method is important as it frees the logical processors for other threads.

printSituation

public static void printSituation()

Prints to System.out a nice outlook of the logical processors situation. It will also show you the machine architecture with chips, cores and processors.