cpu - CPU Representation and Utilities

CPU core representation and filtering.

This module provides a unified representation of logical CPU cores along with filtering capabilities.

When symmetric multiprocessing (SMP or multithreading) is enabled on a server, the physical CPU cores are split into logical CPU cores with different IDs.

LogicalCoreCountFilter filters by the number of logical cores. It’s possible to specify the socket from which to filter the number of logical cores. It’s also possible to not use all logical CPU cores from each physical core (e.g. only the first logical core of each physical core).

LogicalCoreListFilter filters by logical core IDs. This mostly checks that the logical cores are actually present on the server.

class LogicalCore

Bases: object

Representation of a logical CPU core.

A physical core is represented in OS by multiple logical cores (lcores) if CPU multithreading is enabled. When multithreading is disabled, their IDs are the same.

lcore

The logical core ID of a CPU core. It’s the same as core with disabled multithreading.

Type:

int

core

The physical core ID of a CPU core.

Type:

int

socket

The physical socket ID where the CPU resides.

Type:

int

node

The NUMA node ID where the CPU resides.

Type:

int

__init__(lcore: int, core: int, socket: int, node: int) → None
class LogicalCoreList

Bases: object

A unified way to store LogicalCores.

Create a unified format used across the framework and allow the user to use either a str representation (using str(instance) or directly in f-strings) or a list representation (by accessing the lcore_list property, which stores logical core IDs).

__init__(lcore_list: list[int] | list[str] | list[framework.testbed_model.cpu.LogicalCore] | str)

Process lcore_list, then sort.

There are four supported logical core list formats:

lcore_list=[LogicalCore1, LogicalCore2]  # a list of LogicalCores
lcore_list=[0,1,2,3]        # a list of int indices
lcore_list=['0','1','2-3']  # a list of str indices; ranges are supported
lcore_list='0,1,2-3'        # a comma delimited str of indices; ranges are supported
Parameters:

lcore_list (list[int] | list[str] | list[framework.testbed_model.cpu.LogicalCore] | str) – Various ways to represent multiple logical cores. Empty lcore_list is allowed.

property lcore_list: list[int]

The logical core IDs.

class LogicalCoreCount

Bases: object

Define the number of logical cores per physical cores per sockets.

lcores_per_core: int

Use this many logical cores per each physical core.

cores_per_socket: int

Use this many physical cores per each socket.

socket_count: int

Use this many sockets.

sockets: list[int] | None

Use exactly these sockets. This takes precedence over socket_count, so when sockets is not None, socket_count is ignored.

__init__(lcores_per_core: int = 1, cores_per_socket: int = 2, socket_count: int = 1, sockets: list[int] | None = None) → None
class LogicalCoreFilter

Bases: ABC

Common filtering class.

Each filter needs to be implemented in a subclass. This base class sorts the list of cores and defines the filtering method, which must be implemented by subclasses.

__init__(lcore_list: list[framework.testbed_model.cpu.LogicalCore], filter_specifier: framework.testbed_model.cpu.LogicalCoreCount | framework.testbed_model.cpu.LogicalCoreList, ascending: bool = True)

Filter according to the input filter specifier.

The input lcore_list is copied and sorted by physical core before filtering. The list is copied so that the original is left intact.

Parameters:
abstract filter() → list[framework.testbed_model.cpu.LogicalCore]

Filter the cores.

Use self._filter_specifier to filter self._lcores_to_filter and return the filtered LogicalCores. self._lcores_to_filter is a sorted copy of the original list, so it may be modified.

Returns:

The filtered cores.

Return type:

list[framework.testbed_model.cpu.LogicalCore]

class LogicalCoreCountFilter

Bases: LogicalCoreFilter

Filter cores by specified counts.

Filter the input list of LogicalCores according to specified rules:

  • The input filter_specifier is LogicalCoreCount,

  • Use cores from the specified number of sockets or from the specified socket ids,

  • If sockets is specified, it takes precedence over socket_count,

  • From each of those sockets, use only cores_per_socket of cores,

  • And for each core, use lcores_per_core of logical cores. Hypertheading must be enabled for this to take effect.

filter() → list[framework.testbed_model.cpu.LogicalCore]

Filter the cores according to LogicalCoreCount.

Start by filtering the allowed sockets. The cores matching the allowed sockets are returned. The cores of each socket are stored in separate lists.

Then filter the allowed physical cores from those lists of cores per socket. When filtering physical cores, store the desired number of logical cores per physical core which then together constitute the final filtered list.

Returns:

The filtered cores.

Return type:

list[framework.testbed_model.cpu.LogicalCore]

class LogicalCoreListFilter

Bases: LogicalCoreFilter

Filter the logical CPU cores by logical CPU core IDs.

This is a simple filter that looks at logical CPU IDs and only filter those that match.

The input filter is LogicalCoreList. An empty LogicalCoreList won’t filter anything.

filter() → list[framework.testbed_model.cpu.LogicalCore]

Filter based on logical CPU core ID.

Returns:

The filtered logical CPU cores.

Return type:

list[framework.testbed_model.cpu.LogicalCore]

lcore_filter(core_list: list[framework.testbed_model.cpu.LogicalCore], filter_specifier: framework.testbed_model.cpu.LogicalCoreCount | framework.testbed_model.cpu.LogicalCoreList, ascending: bool) → LogicalCoreFilter

Factory for providing the filter that corresponds to filter_specifier.

Parameters:
Returns:

The filter that corresponds to filter_specifier.

Return type:

LogicalCoreFilter