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

All Methods Static Methods Instance Methods Concrete Methods
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 Affinity`	`getAffinity(java.lang.Thread thread)` Obtain the affinity of the current thread.
`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`	`getCurrentAffinity()` Obtain the affinity of the current thread.
`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.
  - getAffinity
```
public static Affinity getAffinity(java.lang.Thread thread)
```
    Obtain the affinity of the current thread.
    
    Returns:
    
    the affinity of this thread context.
    
    Throws:
    
    StaticIllegalArgumentException - when the affinity is not valid.
  - getCurrentAffinity
```
public static Affinity getCurrentAffinity()
```
    Obtain the affinity of the current thread.
    
    Returns:
    
    the affinity of this thread context.
  - 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

Class Affinity

Method Summary

Methods inherited from class java.lang.Object

Method Detail

getPredefinedAffinitiesCount

getPredefinedAffinities

getPredefinedAffinities

isSetAffinitySupported

generate

getRootAffinity

getAffinity

getCurrentAffinity

getAvailableProcessors

getAvailableProcessors

isAffinityChangeNotificationSupported

getProcessorAddedEvent

setProcessorAddedEvent

getProcessorRemovedEvent

setProcessorRemovedEvent

getProcessors

getProcessors

isProcessorInSet

getProcessorCount

isValid

subsumes

clone