Package net.sf.eBus.config

Class ThreadAffinityConfigure

  • public class ThreadAffinityConfigure
extends java.lang.Object
    This immutable class contains the necessary information needed to create an affinity between a thread and a core using OpenHFT Thread Affinity Library. User is assumed to understand thread affinity and the necessary operating system configuration needed to support it. Please see the above link for more information on how to use thread affinity and its correct use.

    ThreadAffinityConfigure consist of the following properties:

    • affinityType: Required. Defines how core is acquired for the thread. There are five acquisition types as defined by ThreadAffinityConfigure.AffinityType:
      1. ANY_CORE: Use AffinityLock.acquireCore() to assign any free core to thread.
      2. ANY_CPU: Use AffinityLock.acquireLock() to assign any free CPU to thread.
      3. CPU_LAST_MINUS: Use AffinityLock.acquireLock(int cpuId to assign a CPU with specified identifier to thread. Requires property CPU_OFFSET_KEY be set.
      4. CPU_ID: Use AffinityLock.acquireLock(int cpuId to assign a CPU with specified identifier to thread. Requires property CPU_ID_KEY be set.
      5. CPU_STRATEGIES: Use AffinityLock.acquireLock(AffinityStrategies...) to assign a CPU for thread affinity. Selects a CPU for thread affinity based on the given selection strategies. Requires property STRATEGIES_KEY be set.

        Please note that this type may not be used by itself or as an initial CPU acquisition type. Rather there must be previous CPU allocation to this (for example a previous dispatcher configuration using thread affinity) which the strategy then uses to allocate the next CPU. Attempts to use this acquisition type either by itself or as the first strategy will result in an error and no CPU allocated for the thread.

    • bind: Optional, default value is false. If true, then bind current thread to allocated AffinityLock.
    • wholeCore: Optional, default value is false. If true, then bind current thread to allocated AffinityLock reserving the whole core. This property is used only when bind property is true.
    • cpuId: Required when affinityType is set to CPU_ID. Specifies the allocated CPU by its identifier.
    • cpuStrategies: Required when affinityType is set to CPU_STRATEGIES. Values are restricted to enum net.openhft.affinity.AffinityStrategies.

      Note: strategy ordering is important. AffinityStrategies.ANY must appear as the last listed strategy. This allows any CPU to be selected in case none of the other strategies found an acceptable CPU.

    Users should be familiar with the OpenHFT Java Thread Affinity library and how it works before using eBus thread affinity configuration. This includes configuring the operating system to isolate acquired CPUs from the operating system. This prevents the OS from pre-empting the thread from its assigned CPU which means the thread does not entirely own the CPU. That said, isolating too many CPUs from the OS can lead to a kernel panic. So using thread affinity is definitely an advanced software technique, requiring good understanding of how an OS functions.

    The following example shows how to use thread affinity for eBus dispatcher threads and especially the CPU_STRATEGIES acquisition type. 

    "dispatchers" : [
    {
        "name" : "mdDispatcher"
        "numberThreads" : 1
        "runQueueType" : "spinning"
        "priority" : 9
        "quantum" : 10000
        "isDefault" : false
        "classes" : [ "com.acme.trading.MDHandler" ]
        "threadAffinity" {       // optional, selector thread core affinity
            affinityType : CPU_ID // required, core selection type.
            cpuId : 7             // required for CPU_ID affinity type
            bind : true           // optional, defaults to false
            wholeCore : true      // optional, defaults to false
        }
    },
    {
        "name" : "orderDispatcher"
        "numberThreads" : 1
        "runQueueType" : "spinning"
        "priority" : 9
        "quantum" : 10000
        "isDefault" : false
        "classes" : [ "com.acme.trading.OrderHandler" ]
        "threadAffinity" {       // optional, selector thread core affinity
            affinityType : CPU_STRATEGIES // required, core selection type.
            cpuStrategies : [             // required for CPU_STRATEGIES affinity type
                        SAME_CORE, SAME_SOCKET, ANY // Note: ANY must be last strategy.
            ]
            bind : true           // optional, defaults to false
            wholeCore : true      // optional, defaults to false
        }
    },
    {
        "name" : "defaultDispatcher"
        "numberThreads" : 8
        "runQueueType" : "blocking"
        "priority" : 4
        "quantum" : 100000
        "isDefault" : true
    }
]

    eBus uses this configuration to optionally pin net.sf.eBus.net.SelectorThread and net.sf.eBus.client.EClient.RQThread instances to a core or cores.

    Author:
    Charles W. Rapp
    See Also:
    ThreadAffinityConfigure.Builder

    • Method Detail

      • equals

        public boolean equals​(java.lang.Object o)
        Overrides:
        equals in class java.lang.Object

      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class java.lang.Object

      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object

      • affinityType

        public ThreadAffinityConfigure.AffinityType affinityType()
        Returns affinity type used for creating thread affinity to selected CPU_ID.
        Returns:
        CPU_ID selection type.

      • bindFlag

        public boolean bindFlag()
        Returns the bind-thread-to-affinity lock setting. If true then thread is bound to the lock.
        Returns:
        true if thread is bound to the affinity lock.
        See Also:
        wholeCoreFlag()

      • wholeCoreFlag

        public boolean wholeCoreFlag()
        Returns whole core reservation bind settings. If true then thread reserves entire core and does not allow hyper-threading. This value is used only if bindFlag() returns true; otherwise it is ignored.
        Returns:
        whole core reservation flag.
        See Also:
        bindFlag()

      • cpuId

        public int cpuId()
        Returns CPU_ID identifier used for ThreadAffinityConfigure.AffinityType.CPU_ID affinity type. Set to a negative number for any other affinity type.
        Returns:
        CPU_ID identifier or < zero if no identifier specified.

      • strategies

        public java.util.List<net.openhft.affinity.AffinityStrategies> strategies()
        Returns immutable list of CPU_ID selection strategies used for ThreadAffinityConfigure.AffinityType.CPU_STRATEGIES affinity type. Set to null for any other affinity type.
        Returns:
        CPU_ID selection strategies.

      • loadAffinity

        public static ThreadAffinityConfigure loadAffinity​(java.lang.String key,
                                                   com.typesafe.config.Config config)
        Returns a thread affinity configuration loaded from a given JSON configuration under property key.
        Parameters:
        key - affinity key is stored under this property.
        config - JSON configuration.
        Returns:
        thread affinity configuration.
        Throws:
        com.typesafe.config.ConfigException - if config is missing a required property or a property value is invalid.

      • loadAffinities

        public static java.util.List<ThreadAffinityConfigure> loadAffinities​(java.lang.String key,
                                                                     com.typesafe.config.Config config)
        Returns list of thread affinity configurations loaded from given JSON configuration under property key.
        Parameters:
        key - affinity keys stored under this property.
        config - JSON configuration.
        Returns:
        list of thread affinity configurations.
        Throws:
        com.typesafe.config.ConfigException - if config is missing a required property or a property value is invalid.

      • builder

        public static ThreadAffinityConfigure.Builder builder()
        Returns new ThreadAffinityConfigure builder instance. ThreadAffinityConfigure.Builder is the only way to create a thread affinity configuration. It is recommended that a new builder is used to create each new thread affinity configuration.
        Returns:
        thread affinity configuration builder.