javax.realtime
Class Affinity

java.lang.Object
  javax.realtime.Affinity

public class Affinity
extends Object

Affinity provides APIs that permit access to the set of Processors a Thread or BoundAsyncEventHandler is permitted to run on. It also provides APIs to be informed of changes in the number of CPUs available for the Java VM.

An instance of Affinity is an immutable set of processors. The processors are identified by integer numbers with a platform-dependent meaning.

An Affinity can be set to be used by a Thread or a BoundAsyncEventHandler. This setting is modifiable at runtime.

Affinity sets containing more than one processor are only supported for pre-defined affinity sets provided by the VM. getPredefinedAffinities() returns an array of all these predefined sets.

Changes of the number of CPUs available may cause cause failures such as deadlocks. Therefore, dynamically enabling or disabling CPUs should be disabled, at least for those CPUs used for RTSJ threads.

For JamaicaVM, the processors ids correspond to the processor ids that are passed to the VM or to the builder command via options -Xcpus or -XcpusFromEnv.

NYI: UNDER DEVELOPMENT: From the Spec: Real-time threads and bound async event handlers that have processing group parameters are members of that processing group, and their processor affinity is governed by the intersection of the processing group's affinity and the schedulable object's affinity. The affinity set of a processing group must have exactly one processor, so the intersection of that set with the schedulable object's affinity set must contain at most one entry. If the intersection is empty the affinity defaults. Ordinarily, an execution context inherits its creator's affinity set, but: Java threads do not inherit affinity from SOs Unbound async event handlers cannot be assigned a non-default affinity. SOs do not inherit affinity from Java threads. When an execution context does not inherit its creator's affinity set, its initial affinity set defaults according to the rules specified: The default used when a heap-mode SO does not inherit its creator's affinity set, and for all unbound heap-mode async event handlers The default used when a no-heap SO does not inherit its creator's affinity set, and for all unbound no-heap async event handlers. The default used for Java threads created by SOs. This class also controls the default affinity used when a processing group is created using a constructor that does not assign a processing group. When the affinity set of a processing group is permitted to default, it defaults to the set of all available processors. (Which permits each member of the processing group to use the affinity set it would use if it were in no processing group.)

Since:

RTSJ 1.1

Method Summary

static Affinity	generate(BitSet bitSet) Create an affinity set based on the given bitset of processors.
static Affinity	get(BoundAsyncEventHandler baeh) return the affinity set that was set for a given async event handler.
static Affinity	get(ProcessingGroupParameters pgp) Return the affinity set that was set for a given processing group.
static Affinity	get(Thread thread) Return the affinity set that was set for a given thread.
static BitSet	getAvailableProcessors() Short hand for getAvailableProcessors(null).
static BitSet	getAvailableProcessors(BitSet dest) Determine the set of processors that are currently available for the Java VM to execute Java code.
static int	getCurrentProcessor() Return the id of the processor the current thread is running on.
static Affinity	getHeapSoDefaultAffinity() Return the default CPU affinity set for schedulable objects that may access heap memory.
static Affinity	getJavaThreadDefaultAffinity() Return the default CPU affinity set for non-RTSJ normal Java threads.
static Affinity	getNoHeapSoDefaultAffinity() Return the default CPU affinity set for schedulable objects that run in no-heap mode.
static Affinity	getPGroupDefaultAffinity() Return the default CPU affinity set for schedulable objects for which the intersection of their CPU affinity and the affinity set for their ProcessingGroupParameters is empty.
static Affinity[]	getPredefinedAffinities() Short hand for getPredefinedAffinities(null)
static Affinity[]	getPredefinedAffinities(Affinity[] dest) Copy the set of all predefined affinity sets to an array
static int	getPredefinedAffinityCount() Determine the number or predefined affinity sets.
BitSet	getProcessors() Return a newly allocated BitSet containing the CPU ids for the CPUs in this affinity set.
BitSet	getProcessors(BitSet dest) Return a bitset containing the CPU ids for the CPUS in this affinity set.
boolean	isProcessorInSet(int processorNumber) Check if a given processor is part of this affinity set
static boolean	isSetAffinitySupported() Check whether affinity setting (via methods setProcessorAffinity(set, ...) is supported by this VM.
static void	set(Affinity set, BoundAsyncEventHandler baeh) Set the CPU affinity of a given bound async event handler.
static void	set(Affinity set, ProcessingGroupParameters pgp) Set the processors affinity of a given processing group parameters instance.
static void	set(Affinity set, Thread thread) Set the CPU affinity of a given thread.

Methods inherited from class java.lang.Object

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

Method Detail

generate

public static Affinity generate(BitSet bitSet)

Create an affinity set based on the given bitset of processors. Which sets are valid is system dependent. Valid sets are all sets of cardinality 1 and the sets returned by getPredefinedAffinities().

Parameters:

bitSet - the set of CPUs that should be part of the set.

Returns:

the Affinity with result.getProcessors().equals(bitSet).

Throws:

NullPointerException - if bitSet == null;

IllegalArgumentException - if bitSet does not have cardinality one and bitSet is not equal to the processor set of any Affinity returned by getAvailableProcessors().

Since:

RTSJ 1.1

get

public static Affinity get(BoundAsyncEventHandler baeh)

return the affinity set that was set for a given async event handler.

Parameters:

baeh - the async event handler

Returns:

the affinity set that was set for baeh, otherwise getHeapSoDefaultAffinity() or getNoHeapSoDefaultAffinity() depending on whether baeh may access the heap or not.

Throws:

NullPointerException - if baeh == null

Since:

RTSJ 1.1

get

public static Affinity get(Thread thread)

Return the affinity set that was set for a given thread.

Parameters:

thread - the thread

Returns:

that affinity set that was set for thread, otherwise getNoHeapSoDefaultAffinity(), getHeapSoDefaultAffinity(), or getJavaThreadDefaultAffinity() depending on whether thread is a NoHeapRealtimeThread, a RealtimeThread or a normal Java Thread.

Throws:

NullPointerException - if thread == null

Since:

RTSJ 1.1

get

public static Affinity get(ProcessingGroupParameters pgp)

Return the affinity set that was set for a given processing group.

Parameters:

pgp - the ProcessingGroupParameters of the processing group.

Returns:

that affinity set that was set for pgp, otherwise getPGroupDefaultAffinity().

Throws:

NullPointerException - if pgp == null

Since:

RTSJ 1.1

getAvailableProcessors

public static BitSet getAvailableProcessors()

Short hand for getAvailableProcessors(null).

Returns:

result of getAvailableProcessors(null).

Since:

RTSJ 1.1

getAvailableProcessors

public static BitSet getAvailableProcessors(BitSet dest)

Determine the set of processors that are currently available for the Java VM to execute Java code. This set may change dynamically. For JamaicaVM, dynamic modifications of the set of available CPUs is currently not supported. The OS must be configured such that the CPU set provided to JamaicaVM via the -Xcpus argument is always available to the VM.

Parameters:

dest - a bitset to receive the set of available CPUs. May be null to ask for allocation of a new bitset.

Returns:

the set of CPUs available. These CPUs are valid to be used as argument in generate(BitSet).

Since:

RTSJ 1.1

getCurrentProcessor

public static int getCurrentProcessor()

Return the id of the processor the current thread is running on.

Returns:

the id of the current CPU, one of the ids in getAvailableProcessors.

Throws:

UnsupportedOperationException - if this operation is not supported on the current system.

getHeapSoDefaultAffinity

public static Affinity getHeapSoDefaultAffinity()

Return the default CPU affinity set for schedulable objects that may access heap memory.

Returns:

the affinity set, never null.

Since:

RTSJ 1.1

getJavaThreadDefaultAffinity

public static Affinity getJavaThreadDefaultAffinity()

Return the default CPU affinity set for non-RTSJ normal Java threads.

Returns:

the affinity set, never null.

Since:

RTSJ 1.1

getNoHeapSoDefaultAffinity

public static Affinity getNoHeapSoDefaultAffinity()

Return the default CPU affinity set for schedulable objects that run in no-heap mode.

Returns:

the affinity set, never null.

Since:

RTSJ 1.1

getPGroupDefaultAffinity

public static Affinity getPGroupDefaultAffinity()

Return the default CPU affinity set for schedulable objects for which the intersection of their CPU affinity and the affinity set for their ProcessingGroupParameters is empty.

Returns:

the affinity set, never null.

Since:

RTSJ 1.1

getPredefinedAffinityCount

public static int getPredefinedAffinityCount()

Determine the number or predefined affinity sets.

Returns:

the number of predefined affinity sets, > 0.

Since:

RTSJ 1.1

getPredefinedAffinities

public static Affinity[] getPredefinedAffinities()

Short hand for getPredefinedAffinities(null)

Returns:

getPredefinedAffinities(null).

Since:

RTSJ 1.1

getPredefinedAffinities

public static Affinity[] getPredefinedAffinities(Affinity[] dest)

Copy the set of all predefined affinity sets to an array

Parameters:

dest - (out!) the array the predefined sets should be copied to, null to allocate a new array.

Returns:

dest or a newly allocated array in case dest == null. Entries dest[i] for getPredefinedAffinityCount() <= i < dest.length will be set to null.

Throws:

IllegalArgumentException - in case dest!= null but dest.length() < getPredefinedAffinityCount().

Since:

RTSJ 1.1

isSetAffinitySupported

public static boolean isSetAffinitySupported()

Check whether affinity setting (via methods setProcessorAffinity(set, ...) is supported by this VM.

Returns:

true iff affinity setting is supported.

Since:

RTSJ 1.1

set

public static void set(Affinity set,
                       BoundAsyncEventHandler baeh)
                throws ProcessorAffinityException

Set the CPU affinity of a given bound async event handler. The new affinity may not become effective immediately, but at the latest at the next release time after the call to set().

Parameters:

set - the affinity set

baeh - the bound async event handler whose CPU affinity is to be set

Throws:

NullPointerException - if set == null or baeh == null

ProcessorAffinityException - if !isSetAffinitySupported.

Since:

RTSJ 1.1

set

public static void set(Affinity set,
                       Thread thread)
                throws ProcessorAffinityException

Set the CPU affinity of a given thread. For JamaicaVM, the new affinity may not become effective immediately, but at the latest after one of the following operations: thread blocks (doing Object.wait(), entering a synchronized block with contention, Thread.sleep(), Thread.join(), RealtimeThread.waitForNextPeriod()), or thread yields (via Thread.yield()) or thread is preempted by a higher priority thread. For JamaicaVM, a thread that is in a JNI method is not immediately affected by the affinity change, but only after it returns and performs one of the above operations.

Parameters:

set - the CPU affinity

thread - the thread whose affinity is to be set.

Throws:

NullPointerException - if set == null or thread == null.

ProcessorAffinityException - if !isSetAffinitySupported.

Since:

RTSJ 1.1

set

public static void set(Affinity set,
                       ProcessingGroupParameters pgp)
                throws ProcessorAffinityException

Set the processors affinity of a given processing group parameters instance.

Parameters:

set - the affinity set

pgp - the ProcessingGroupParameters

Throws:

NullPointerException - if set == null or pgp == null.

ProcessorAffinityException - if !isSetAffinitySupported.

Since:

RTSJ 1.1

getProcessors

public BitSet getProcessors()

Return a newly allocated BitSet containing the CPU ids for the CPUs in this affinity set.

Returns:

the set of CPUs in this affinity set as a new instance.

Since:

RTSJ 1.1

getProcessors

public final BitSet getProcessors(BitSet dest)

Return a bitset containing the CPU ids for the CPUS in this affinity set.

Parameters:

dest - (out!) the bitset to store the result in, null to force allocation of a new result.

Returns:

dest if dest != null, a newly allocated bitset otherwise.

Since:

RTSJ 1.1

isProcessorInSet

public final boolean isProcessorInSet(int processorNumber)

Check if a given processor is part of this affinity set

Returns:

true iff processorNumber is in this set.

Since:

RTSJ 1.1