javax.realtime

Class Affinity

java.lang.Object

javax.realtime.Affinity

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable

public final class Affinity
extends java.lang.Object
implements java.lang.Cloneable, java.io.Serializable

This is class for specifying processor affinity. It includes a factory that generates Affinity objects. With it, the affinity of every task in a JVM can be controlled.

An affinity is a set of processors that can be associated with certain types of tasks. Each task can be associated with an affinity via its SchedulingParameters. Groups of these can be assigned an affinity through their RealtimeThreadGroup.

The processor membership of an affinity is immutable. The tasks associations of an affinity are mutable. The internal representation of a set of processors in an Affinity instance is not specified, but the representation that is used to communicate with this class is a BitSet where each bit corresponds to a logical processor ID. The relationship between logical and physical processors is beyond the scope of this specification, and may change.

The set of affinities created at startup (the predefined set) is visible through the getPredefinedAffinities(Affinity[]) method. Only the Affinities made available at startup and the Affinities generated using generate(BitSet) but with a cardinality of one may be used as parameters for schedulables. These are referred to as \emph{valid} affinities. However, it is still possible to create Affinity instances that are not equals to the ones defined at startup and with a cardinality more than one using generate(BitSet). These affinities are not considered to be valid as they can not be used as parameters for schedulables. The purpose of these invalid affinities is to be used as parameter if a RealtimeThreadGroup instance to limit the processors available to its members.

There is no public constructor for this class. All instances must be created by the factory method (generate).

Since:

RTSJ 2.0

See Also:

Serialized Form

Method Summary

Modifier and Type	Method and Description
java.lang.Object	clone()
static Affinity	generate(java.util.BitSet set) Determines the Affinity corresponding to a BitSet, where each bit in set represents a CPU.
static java.util.BitSet	getAvailableProcessors() This method is equivalent to getAvailableProcessors(BitSet) with a null argument.
static java.util.BitSet	getAvailableProcessors(java.util.BitSet dest) In systems where the set of processors available to a process is dynamic (e.g., because of system management operations or because of fault tolerance capabilities), the set of available processors shall reflect the processsors that are allocated to the RTSJ runtime and are currently available to execute tasks.
static Affinity[]	getPredefinedAffinities() Equivalent to invoking getPredefinedAffinitySets(null).
static Affinity[]	getPredefinedAffinities(Affinity[] dest) Determines what affinities are predefined by the Java runtime.
static int	getPredefinedAffinitiesCount() Determines the minimum array size required to store references to all the predefined processor affinities.
static AsyncEvent	getProcessorAddedEvent() Gets the event used for CPU addition notification.
int	getProcessorCount() Determines the number of CPUs in this affinity
static AsyncEvent	getProcessorRemovedEvent() Gets the event used for CPU removal notification.
java.util.BitSet	getProcessors() Obtains a BitSet representing the processor affinity set for this Affinity.
java.util.BitSet	getProcessors(java.util.BitSet dest) Determines the set of CPUs representing the processor affinity of this Affinity.
static Affinity	getRootAffinity() Gets the root Affinity: the Affinity that can be used to allow a schedulable to run on all the processing units available to the VM.
static boolean	isAffinityChangeNotificationSupported() Determines whether or not the system can trigger an event for notifying the application when the set of available CPUs changes.
boolean	isProcessorInSet(int processorId) Asks whether a processor is included in this affinity set.
static boolean	isSetAffinitySupported() Determines whether or not affinity control is supported.
boolean	isValid() Determine whether or not the affinity can be used for scheduling or just for limiting the processors available to members of RealtimeThreadGroup.
static void	setProcessorAddedEvent(AsyncEvent event) Sets the AsyncEvent that will be fired when a processor is added to the set available to the JVM.
static void	setProcessorRemovedEvent(AsyncEvent event) Sets the AsyncEvent that will be fired when a processor is removed from the set available to the JVM.
boolean	subsumes(Affinity other) Determines whether or not other is equal to or a proper subset of this affinity.

Methods inherited from class java.lang.Object

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

Method Detail

getPredefinedAffinitiesCount

public static final int getPredefinedAffinitiesCount()

Determines the minimum array size required to store references to all the predefined processor affinities.

Returns:

the minimum array size required to store references to all the predefined affinities.

getPredefinedAffinities

public static final Affinity[] getPredefinedAffinities()

Equivalent to invoking getPredefinedAffinitySets(null).

Returns:

an array of the predefined affinities.

getPredefinedAffinities

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

Determines what affinities are predefined by the Java runtime.

Parameters:

dest - The destination array, or null.

Returns:

dest or a newly created array when dest is null, populated with references to the predefined affinities. When dest has excess entries, those entries are filled with null.

Throws:

StaticIllegalArgumentException - when dest is not large enough.

isSetAffinitySupported

public static final boolean isSetAffinitySupported()

Determines whether or not affinity control is supported.

Returns:

true when more than one affinity set is available.

generate

public static final Affinity generate(java.util.BitSet set)

Determines the Affinity corresponding to a BitSet, where each bit in set represents a CPU. When BitSet does not correspond to a predefined affinity or an affinity with a cardinality of one, the resulting Affinity instance is not a valid affinity and can only be used for limiting the CPUs that can be used by a RealtimeThreadGroup. The method isValid() can be used to determine whether or not the result is a valid affinity.

Platforms that support specific affinities will register those Affinity instances with Affinity. They appear in the arrays returned by getPredefinedAffinities() and getPredefinedAffinities(Affinity[]).

Parameters:

set - The BitSet to convert into an Affinity.

Returns:

the resulting Affinity.

Throws:

StaticIllegalArgumentException - when set is null or when set is empty.

getRootAffinity

public static final Affinity getRootAffinity()

Gets the root Affinity: the Affinity that can be used to allow a schedulable to run on all the processing units available to the VM.

Returns:

the root Affinity.

getAvailableProcessors

public static final java.util.BitSet getAvailableProcessors()

This method is equivalent to getAvailableProcessors(BitSet) with a null argument. In systems where the set of processors available to a process is dynamic, e.g., system management operations or fault tolerance capabilities can add or remove processors, the set of available processors shall reflect the processors that are allocated to the RTSJ runtime and are currently available to execute tasks.

Returns:

a BitSet representing the set of processors currently valid for use in the BitSet argument to generate(BitSet).

getAvailableProcessors

public static final java.util.BitSet getAvailableProcessors(java.util.BitSet dest)

In systems where the set of processors available to a process is dynamic (e.g., because of system management operations or because of fault tolerance capabilities), the set of available processors shall reflect the processsors that are allocated to the RTSJ runtime and are currently available to execute tasks.

Parameters:

dest - When dest is non-null, use dest as the returned value. When it is null, create a new BitSet.

Returns:

a BitSet representing the set of processors currently valid for use in the bitset argument to generate(BitSet).

isAffinityChangeNotificationSupported

public static final boolean isAffinityChangeNotificationSupported()

Determines whether or not the system can trigger an event for notifying the application when the set of available CPUs changes.

Returns:

true when change notification is supported. (See setProcessorAddedEvent(AsyncEvent) and setProcessorRemovedEvent(AsyncEvent).)

getProcessorAddedEvent

public static AsyncEvent getProcessorAddedEvent()

Gets the event used for CPU addition notification.

Returns:

the async event that will be fired when a processor is added to the set available to the JVM. Returns null when change notification is not supported, or when no async event has been designated.

setProcessorAddedEvent

public static void setProcessorAddedEvent(AsyncEvent event)
                                   throws StaticUnsupportedOperationException,
                                          StaticIllegalArgumentException

Sets the AsyncEvent that will be fired when a processor is added to the set available to the JVM.

Parameters:

event - The async event to fire in case an added processor is detected, or null to cause no async event to be called in case an added processor is detected.

Throws:

StaticUnsupportedOperationException - when change notification is not supported.

StaticIllegalArgumentException - when event is not in immortal memory.

getProcessorRemovedEvent

public static AsyncEvent getProcessorRemovedEvent()

Gets the event used for CPU removal notification.

Returns:

the async event that will be fired when a processor is removed from the set available to the JVM. Returns null when change notification is not supported, or when no async event has been designated.

setProcessorRemovedEvent

public static void setProcessorRemovedEvent(AsyncEvent event)

Sets the AsyncEvent that will be fired when a processor is removed from the set available to the JVM.

Parameters:

event - Called when a processor is removed.

Throws:

StaticUnsupportedOperationException - when change notification is not supported.

StaticIllegalArgumentException - when event is not null or in immortal memory.

getProcessors

public final java.util.BitSet getProcessors()

Obtains a BitSet representing the processor affinity set for this Affinity.

Returns:

a newly created BitSet representing this Affinity.

getProcessors

public final java.util.BitSet getProcessors(java.util.BitSet dest)

Determines the set of CPUs representing the processor affinity of this Affinity.

Parameters:

dest - Set dest to the BitSet value. When dest is null, create a new BitSet in the current allocation context.

Returns:

a BitSet representing the processor affinity set of this Affinity.

isProcessorInSet

public final boolean isProcessorInSet(int processorId)

Asks whether a processor is included in this affinity set.

Parameters:

processorId - A number identifying a single CPU in a multiprocessor system.

Returns:

true when and only when processorNumber is represented in this affinity set.

getProcessorCount

public int getProcessorCount()

Determines the number of CPUs in this affinity

Returns:

the number of CPUs.

isValid

public boolean isValid()

Determine whether or not the affinity can be used for scheduling or just for limiting the processors available to members of RealtimeThreadGroup.

Returns:

true when valid for scheduling and false otherwise.

subsumes

public boolean subsumes(Affinity other)

Determines whether or not other is equal to or a proper subset of this affinity.

Parameters:

other - The other affinity with which to compare

Returns:

true Only when the affinity in parameter is a equal to or a proper subset of this affinity.

clone

public java.lang.Object clone()

Overrides:

clone in class java.lang.Object