ILimitedCpuInfo_abi#

Fully qualified name: omni::platforminfo::ILimitedCpuInfo_abi

Defined in omni/platforminfo/ILimitedCpuInfo.h

class ILimitedCpuInfo_abi : public omni::core::Inherits<omni::core::IObject, std::integral_constant<uint64_t, carb::fnv1aHash("omni.platforminfo.ILimitedCpuInfo")>::value>#

Interface to collect information about the CPUs installed in the calling system.

This can provide some basic information about the CPU(s) and get access to features that are supported by them. The values reported from this interface will reflect any CPU resource limitations imposed on the system by an external source. For example, the available CPUs could be limited in a container, a VM, or by an OS level per-user quota.

This interface has mostly the same set of functions that the omni::platforminfo::ICpuInfo interface does. The only difference is in its behavior - it will retrieve the CPU info available to the calling process under a resource limiting system such as Docker or a CM instead of the bare metal values. If no limits are set on the container or VM, this will fall back to reporting the same bare metal values as omni::platforminfo::ICpuInfo instead.

Some of the functions of omni::platforminfo::ICpuInfo have been removed here since they do not make sense in a resource limiting situation. Some new functions have also been added to retrieve more specific CPU core limiting information.

Note

The CPU information will only be collected once on loading this plugin and cached for later retrieval. If the CPU core allocation changes dynamically while the calling process is still running (and therefore the container is still running), this change will not be reflected in the returned values.

Subclassed by omni::core::Generated< omni::platforminfo::ILimitedCpuInfo_abi >

Public Functions

inline void *cast(omni::core::TypeId id) noexcept#

Returns a pointer to the interface defined by the given type id if this object implements the type id’s interface.

Objects can support multiple interfaces, even interfaces that are in different inheritance chains.

The returned object will have omni::core::IObject::acquire() called on it before it is returned, meaning it is up to the caller to call omni::core::IObject::release() on the returned pointer.

The returned pointer can be safely reinterpret_cast<> to the type id’s C++ class. For example, “omni.windowing.IWindow” can be cast to omni::windowing::IWindow.

Do not directly use this method, rather use a wrapper function like omni::core::cast() or omni::core::ObjectPtr::as().

Thread Safety: This method is thread safe.

inline void acquire() noexcept#

Increments the object’s reference count.

Objects may have multiple reference counts (e.g. one per interface implemented). As such, it is important that you call omni::core::IObject::release() on the same pointer from which you called omni::core::IObject::acquire().

Do not directly use this method, rather use omni::core::ObjectPtr, which will manage calling omni::core::IObject::acquire() and omni::core::IObject::release() for you.

Thread Safety: This method is thread safe.

inline void release() noexcept#

Decrements the objects reference count.

Most implementations will destroy the object if the reference count reaches 0 (though this is not a requirement).

Objects may have multiple reference counts (e.g. one per interface implemented). As such, it is important that you call omni::core::IObject::release() on the same pointer from which you called omni::core::IObject::acquire().

Do not directly use this method, rather use omni::core::ObjectPtr, which will manage calling omni::core::IObject::acquire() and omni::core::IObject::release() for you.

Thread Safety: This method is thread safe.

Protected Functions

virtual size_t getCpuPackageCount_abi() noexcept = 0#

Retrieves the total number of CPU packages installed on the system.

Remark

A system may have multiple CPUs installed if the motherboard supports it. At least in the Intel (and compatible) case, there are some restrictions to doing this - all CPUs must be in the same family, share the same core count, feature set, and bus speed. Outside of that, the CPUs do not need to be identical. Note however that if the OS or container is limiting the number of available cores, the core count may not match in each package.

Thread Safety: This call is thread safe.

Returns:: The total number of CPU packages installed in the system. A CPU package is a single physical CPU chip that is connected to a physical socket on the motherboard.

virtual size_t getTotalPhysicalCoreCount_abi() noexcept = 0#

Retrieves an estimate of the total number of physical cores across all CPUs in the system.

Thread Safety: This call is thread safe.

Note

Because the available CPU cores may be limited in a container or at the OS level, it is possible that this may be an odd number. It is also possible that the number of logical cores may not be an integer multiple of the number of physical cores. This is expected behavior since the CPU set may have asymmetrically limited the cores between packages. It is most reliable to simply use the total number of logical cores to decide on things like worker thread counts or task load estimates.

Note

Since any of the CPU’s cores can be assigned to a container or control group, it is possible that fewer than all of the logical cores in a physical core could be assigned to the container. This means that the physial core count can at best be an estimate. This is typically just treated as one logical core per physical core in that case. For this reason, the number of physical cores may be reported incorrectly, sometimes even to the point where more physical cores are reported than the bare metal hardware actually has. Thus it is most accurate to retrieve and make decisions based on the logical core count, not the physical core count.

Returns:: An estimate of the total number of physical cores across all available CPUs in the system. This includes the sum of all available physical cores on all CPU packages. This will not be zero.

virtual size_t getTotalLogicalCoreCount_abi() noexcept = 0#

Retrieves the total number of logical cores across all CPUs in the system.

Thread Safety: This call is thread safe.

Note

Because the available CPU cores may be limited in a container or at the OS level, it is possible that this may be an odd number. It is also possible that the number of logical cores may not be an integer multiple of the number of physical cores. This is expected behavior since the CPU set may have asymmetrically limited the cores between packages. It is most reliable to simply use the total number of logical cores to decide on things like worker thread counts or task load estimates.

Note

Also note that because of the way CPU cores can be assigned to VMs or containers, it may appear that there is only one logical core per physical core even when the underlying bare metal hardware supports multiple logical cores per physical core. There is unfortunately no way around this since it has been limited at the OS or VM level.

Returns:: The total number of logical cores across all CPUs in the system. This includes the sum of all logical cores on all CPU packages.

virtual bool isFeatureSupported_abi(CpuFeature feature) noexcept = 0#

Checks if a requested feature is supported by the CPU(s) in the system.

Remark

See omni::platforminfo::CpuFeature for more information on the features that can be queried.

Thread Safety: This call is thread safe.

Returns:: true if the requested feature is supported. Returns false otherwise.

virtual const char *getPrettyName_abi(size_t cpuIndex) noexcept = 0#

Retrieves the friendly name of a CPU in the system.

Thread Safety: This call is thread safe.

Note

This CPU pretty name string will still be retrieved from the CPU itself even if access to CPU cores has been limited.

Parameters:: cpuIndex – [in] The zero based index of the CPU package to retrieve the name for. This should be less than the return value of omni::platforminfo::ILimitedCpuInfo::getCpuPackageCount().
Returns:: The friendly name of the requested CPU package. This string should be suitable for display to the user. This will contain a rough outline of the processor model and architecture. It may or may not contain the clock speed.

virtual const char *getIdentifier_abi(size_t cpuIndex) noexcept = 0#

Retrieves the identifier of a CPU in the system.

Thread Safety: This call is thread safe.

Note

This CPU identifier string will still be retrieved from the CPU itself even if access to CPU cores has been limited.

Parameters:: cpuIndex – [in] The zero based index of the CPU package to retrieve the identifier for. This should be less than the return value of omni::platforminfo::ILimitedCpuInfo::getCpuPackageCount().
Returns:: The identifier string of the requested CPU package. This string should be suitable for display to the user. This will contain information about the processor family, vendor, and architecture.

virtual const char *getVendor_abi(size_t cpuIndex) noexcept = 0#

Retrieves the vendor string for a CPU package in the system.

Thread Safety: This call is thread safe.

Note

This CPU vendor string will still be retrieved from the CPU itself even if access to CPU cores has been limited.

Parameters:: cpuIndex – [in] The zero based index of the CPU package to retrieve the vendor for. This should be less than the return value of omni::platforminfo::ILimitedCpuInfo::getCpuPackageCount().
Returns:: The name of the vendor as reported by the CPU itself. This may be something along the lines of “GenuineIntel” or “AuthenticAMD” for x86_64 architectures, or the name of the CPU implementer for ARM architectures.

virtual uint64_t getProcessorMask_abi(size_t cpuIndex) noexcept = 0#

Retrieves a bit mask for the processor cores in a CPU package in the system.

Thread Safety: This call is thread safe.

Note

The mask may be 0 if out of range of 64 bits.

Parameters:: cpuIndex – [in] The zero based index of the CPU package to retrieve the identifier for. This should be less than the return value of omni::platforminfo::ILimitedCpuInfo::getCpuPackageCount().
Returns:: A mask identifying which CPU cores the given CPU covers. A set bit indicates a core that belongs to the given CPU. A 0 bit indicates either a core from another package or a non-existent core. This may also be 0 if more than 64 cores are present in the system or they are out of range of a single 64-bit value.

virtual int32_t getCoreUsageQuota_abi() noexcept = 0#

Retrieves the effective CPU usage quota.

Remark

The CPU usage quota is an estimate of how many cores a process can effectively use. However, it does not mean that the process is restricted to only running on only a specific subset of cores. Instead it means that the threads of the process will only be scheduled to run for a portion of the total available time the CPU has. On Linux, this is expressed as a ratio of available run time versus a scheduling period. The scheduling period is 100000us by default and the run quota is expressed as the number of microseconds a given process is able to use out of that period. For example, a quota of 25000us means that the process may effectively use 25% of a single core’s processing time. A value of 275000us means that the process may effectively use 275% of a single core’s processing time (ie: it can effectively use 2.75 cores). Note that providing a quota value less than the period (ie: the 25000us example) does not mean that only one core may be used. The host OS is still free to schedule the process’ threads in parallel as needed, it just limits the number of time slices of the CPU’s time that it can use over a given period.

Remark

The value returned here is the effective CPU usage quota rounded up or down to the nearest full core. This can be used as an estimate of how many CPU cores the calling process effectively has access to. Note that the given quota may still be larger than the total number of logical cores available to the process. This can occur in cases where both a CPU quota and a CPU set are specified for a container. In this case, the caller will need to clamp the value to the total number of logical cores as returned from omni::platforminfo::ILimitedCpuInfo::getTotalLogicalCoreCount().

Thread Safety: This call is thread safe.

Returns:: The effective CPU usage quota. This is expressed as an estimate of how many cores the threads of the calling process can effectively be scheduled on. Note that this may be less than, equal to, or greater than the total logical core count available to the calling process.

virtual bool getCoreSetList_abi( int32_t *cores, size_t maxCores, ) noexcept = 0#

Retrieves the set of CPU cores available to the calling process.

Thread Safety: This call is thread safe.

Parameters:

cores – [out] Receives the list of core indices for all CPU cores available to the calling process. If no CPU set has been defined that limits access to specific cores, this will simply return a list of all core indices on the bare metal CPU. This may not be nullptr. This buffer should be large enough to hold as many core indices as omni::platforminfo::ILimitedCpuInfo::getTotalLogicalCoreCount().
maxCores – [in] The maximum number of CPU core indices that can fit in cores.

Returns:

true if the CPU core list is successfully returned. Returns false if the cores buffer is too small to hold the full core indices list.

virtual size_t getPhysicalCoreCountForPackage_abi( size_t cpuIndex, ) noexcept = 0#

Retrieves the physical CPU core count for a specific CPU package.

Thread Safety: This call is thread safe.

Parameters:: cpuIndex – [in] The CPU package to retrieve the physical core count for. This must be less than the value returned from omni::platforminfo::ILimitedCpuInfo::getCpuPackageCount().
Returns:: The estimated number of physical CPU cores on the requested CPU package. Note that this is only an estimate since logical cores may be assigned asymmetrically in a container or VM. This is estimated using the bare metal physical-vs-logical core multiplier. It is most accurate to only use the logical core count when making decisions based off of the CPU core count.

virtual size_t getLogicalCoreCountForPackage_abi( size_t cpuIndex, ) noexcept = 0#

Retrieves the logical CPU core count for a specific CPU package.

Thread Safety: This call is thread safe.

Parameters:: cpuIndex – [in] The CPU package to retrieve the logical core count for. This must be less than the value returned from omni::platforminfo::ILimitedCpuInfo::getCpuPackageCount().
Returns:: The total number of logical CPU cores on the requested CPU package. This will never be 0. Any CPU packages that do not have cores assigned to them in the limited CPU resource case will be removed.

virtual void *cast_abi(TypeId id) noexcept = 0#

Returns a pointer to the interface defined by the given type id if this object implements the type id’s interface.

Objects can support multiple interfaces, even interfaces that are in different inheritance chains.

The returned object will have omni::core::IObject::acquire() called on it before it is returned, meaning it is up to the caller to call omni::core::IObject::release() on the returned pointer.

The returned pointer can be safely reinterpret_cast<> to the type id’s C++ class. For example, “omni.windowing.IWindow” can be cast to omni::windowing::IWindow.

Do not directly use this method, rather use a wrapper function like omni::core::cast() or omni::core::ObjectPtr::as().

Thread Safety: This method is thread safe.

virtual void acquire_abi() noexcept = 0#

Increments the object’s reference count.

Objects may have multiple reference counts (e.g. one per interface implemented). As such, it is important that you call omni::core::IObject::release() on the same pointer from which you called omni::core::IObject::acquire().

Do not directly use this method, rather use omni::core::ObjectPtr, which will manage calling omni::core::IObject::acquire() and omni::core::IObject::release() for you.

Thread Safety: This method is thread safe.

virtual void release_abi() noexcept = 0#

Decrements the objects reference count.

Most implementations will destroy the object if the reference count reaches 0 (though this is not a requirement).

Objects may have multiple reference counts (e.g. one per interface implemented). As such, it is important that you call omni::core::IObject::release() on the same pointer from which you called omni::core::IObject::acquire().

Do not directly use this method, rather use omni::core::ObjectPtr, which will manage calling omni::core::IObject::acquire() and omni::core::IObject::release() for you.

Thread Safety: This method is thread safe.