javax.realtime

Class Affinity

java.lang.Object

javax.realtime.Affinity

All Implemented Interfaces:

Serializable, Cloneable

public final class Affinity
extends Object
implements Serializable, Cloneable

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 the option -Xcpus.

Since:

RTSJ 2.0

See Also:

Serialized Form

Method Summary

Modifier and Type	Method and Description
Object	clone() Creates and returns a copy of this object.
boolean	equals(Object other) Indicates whether some other object is "equal to" this one.
static Affinity	generate(BitSet set) Determines the Affinity corresponding to a BitSet, where each bit in set represents a CPU.
static Affinity	getAffinity(Thread thread) Obtain the affinity of the current 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 Affinity	getCurrentAffinity() Obtain the affinity of the current thread.
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	getPredefinedAffinitiesCount() Determine the number or predefined 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.
BitSet	getProcessors() Return a newly allocated BitSet containing the CPU ids for the CPUs in this affinity set.
BitSet	getProcessors(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) Check whether a processor is included in this affinity set.
static boolean	isSetAffinitySupported() Check whether affinity setting (via methods setProcessorAffinity(set, ...) is supported by this VM.
boolean	isValid() Determines 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.
String	toString() Returns a String representing this Affinity in the form of "Affinity("+processorSet+")".

Methods inherited from class java.lang.Object

finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Method Detail

generate

public static Affinity generate(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 a 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[]).

Throws:

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

Parameters:

set - the set of CPUs that should be in the Affinity.

Returns:

an Affinity such that result.getProcessors().equals(bitSet).

getAvailableProcessors

public static BitSet getAvailableProcessors()

Short hand for getAvailableProcessors(null).

Returns:

result of getAvailableProcessors(null).

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).

getPredefinedAffinitiesCount

public static int getPredefinedAffinitiesCount()

Determine the number or predefined affinities.

Returns:

the number of predefined affinities.

getPredefinedAffinities

public static Affinity[] getPredefinedAffinities()

Short hand for getPredefinedAffinities(null)

Returns:

getPredefinedAffinities(null).

getPredefinedAffinities

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

Copy the set of all predefined affinity sets to an array

Throws:

StaticIllegalArgumentException - in case dest != null but dest.length() < getPredefinedAffinitiesCount().

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 getPredefinedAffinitiesCount() <= i < dest.length will be set to null.

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.

getRootAffinity

public 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.

Returns:

the root Affinity.

getAffinity

public static Affinity getAffinity(Thread thread)

Obtain the affinity of the current thread.

Throws:

StaticIllegalArgumentException - when the affinity is not valid.

Returns:

the affinity of this thread context.

getCurrentAffinity

public static Affinity getCurrentAffinity()

Obtain the affinity of the current thread.

Returns:

the affinity of this thread context.

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.

getProcessors

public final BitSet getProcessors(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)

Check 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 processorId is represented in this affinity set.

isValid

public boolean isValid()

Determines 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.

getProcessorCount

public int getProcessorCount()

Determines the number of CPUs in this affinity

Returns:

the number of CPUs.

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 asynchronous 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 asynchronous 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.

Throws:

StaticUnsupportedOperationException - when change notification is not supported.

StaticIllegalArgumentException - when event is not in immortal memory.

Parameters:

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

getProcessorRemovedEvent

public static AsyncEvent getProcessorRemovedEvent()
                                           throws StaticUnsupportedOperationException

Gets the event used for CPU removal notification.

Throws:

StaticUnsupportedOperationException - when change notification is not supported.

Returns:

the asynchronous 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 asynchronous event has been designated.

setProcessorRemovedEvent

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

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

Throws:

StaticUnsupportedOperationException - when change notification is not supported.

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

Parameters:

event - Called when a processor is removed.

equals

public boolean equals(Object other)

Description copied from class: Object

Indicates whether some other object is "equal to" this one.

The equals method implements an equivalence relation on non-null object references:

• It is reflexive: for any non-null reference value x, x.equals(x) should return true.
• It is symmetric: for any non-null reference values x and y, x.equals(y) should return true if and only if y.equals(x) returns true.
• It is transitive: for any non-null reference values x, y, and z, if x.equals(y) returns true and y.equals(z) returns true, then x.equals(z) should return true.
• It is consistent: for any non-null reference values x and y, multiple invocations of x.equals(y) consistently return true or consistently return false, provided no information used in equals comparisons on the objects is modified.
• For any non-null reference value x, x.equals(null) should return false.

The equals method for class Object implements the most discriminating possible equivalence relation on objects; that is, for any non-null reference values x and y, this method returns true if and only if x and y refer to the same object (x == y has the value true).

Note that it is generally necessary to override the hashCode method whenever this method is overridden, so as to maintain the general contract for the hashCode method, which states that equal objects must have equal hash codes.

Overrides:

equals in class Object

Parameters:

other - the reference object with which to compare.

Returns:

true if this object is the same as the obj argument; false otherwise.

See Also:

Object.hashCode(), HashMap

toString

public String toString()

Returns a String representing this Affinity in the form of "Affinity("+processorSet+")". Example: Affinity({0, 2, 3}) if the affinity allow a schedulable to run on the first, second and third CPU.

Overrides:

toString in class Object

Returns:

a string describing this affinity.

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 Object clone()

Description copied from class: Object

Creates and returns a copy of this object. The precise meaning of "copy" may depend on the class of the object. The general intent is that, for any object x, the expression:

 x.clone() != x

will be true, and that the expression:

 x.clone().getClass() == x.getClass()

will be true, but these are not absolute requirements. While it is typically the case that:

 x.clone().equals(x)

will be true, this is not an absolute requirement.

By convention, the returned object should be obtained by calling super.clone. If a class and all of its superclasses (except Object) obey this convention, it will be the case that x.clone().getClass() == x.getClass().

By convention, the object returned by this method should be independent of this object (which is being cloned). To achieve this independence, it may be necessary to modify one or more fields of the object returned by super.clone before returning it. Typically, this means copying any mutable objects that comprise the internal "deep structure" of the object being cloned and replacing the references to these objects with references to the copies. If a class contains only primitive fields or references to immutable objects, then it is usually the case that no fields in the object returned by super.clone need to be modified.

The method clone for class Object performs a specific cloning operation. First, if the class of this object does not implement the interface Cloneable, then a CloneNotSupportedException is thrown. Note that all arrays are considered to implement the interface Cloneable and that the return type of the clone method of an array type T[] is T[] where T is any reference or primitive type. Otherwise, this method creates a new instance of the class of this object and initializes all its fields with exactly the contents of the corresponding fields of this object, as if by assignment; the contents of the fields are not themselves cloned. Thus, this method performs a "shallow copy" of this object, not a "deep copy" operation.

The class Object does not itself implement the interface Cloneable, so calling the clone method on an object whose class is Object will result in throwing an exception at run time.

Overrides:

clone in class Object

Returns:

a clone of this instance.

See Also:

Cloneable