ms_processors Class Reference

This class is designed to retrieve current CPU configuration on the computer and set affinity. More...

#include <ms_processors.hpp>

Inheritance diagram for ms_processors:

Collaboration diagram for ms_processors:

Public Types
enum	{ DEPRECATED_MAX_CORES_PER_LICENSE = 4 }
	The maximum number of cores that may be used for a single 'cpu' license. More...
enum	HYPERTHREADING {   HT_NOT_CAPABLE = 0 ,   HT_ENABLED = 1 ,   HT_DISABLED = 2 ,   HT_SUPPORTED_NOT_ENABLED = 3 ,   HT_CANNOT_DETECT = 4 }
	Hyper-threading status for the CPUs. More...

Public Member Functions
	ms_processors (bool checkLinuxHT, int unused)
	Retrieves all CPU information immediately.
	ms_processors (const ms_processors &src)
	Copying constructor.
	~ms_processors ()
	Destructor.
void	appendErrors (const ms_errors &src)
	Copies all errors from another instance and appends them at the end of own list.
void	clearAllErrors ()
	Remove all errors from the current list of errors.
void	copyFrom (const ms_errors *right)
	Use this member to make a copy of another instance.
void	copyFrom (const ms_processors *right)
	Allows to make a copy of another instance.
int	getAutoDetectNumThreads (const int numLicensed, const int numCoresPerCpuLicense) const
	Return the 'optimal' number of threads for the license.
int	getCoreFromLogical (const int cpu) const
	For multi-core processors, returns the core number for the give logical CPU.
const ms_errs *	getErrorHandler () const
	Retrive the error object using this function to get access to all errors and error parameters.
int	getHT_IDFromLogical (const int cpu) const
	For Intel processors, return an ID corresponding to the logical processors hyper-threading state.
UINT64	getHyperThreadedCPUsMask () const
HYPERTHREADING	getHyperThreadingState () const
	Returns the hyper-threading state as best as can be detected .
int	getLastError () const
	Return the error description of the last error that occurred.
std::string	getLastErrorString () const
	Return the error description of the last error that occurred.
std::string	getMultithreadedName () const
	Returns a string that describes multithreading or multi-core capabilities.
int	getNumAvailableToProcess () const
	Returns the number of logical CPUs that a process can use.
int	getNumCores (const int packageID=-1) const
	Returns the number of cores on the processor specified by the physical CPU number.
int	getNumLogicalPerPhysical (const int packageID=0) const
	Returns the number of 'logical' CPUs per physical processor.
int	getNumOnSystem () const
	Returns the number of logical CPUs installed in the system.
int	getNumPhysicalOnSystem () const
	Return the number of physical CPUs on a system.
int	getNumProcessorGroups () const
	Return the number of processor groups.
int	getPhysicalFromLogical (const int cpu) const
	Returns the physical CPU number for a given logical CPU number.
std::string	getProcessorName () const
	Returns a string that describes the processor.
UINT64	getWhichAvailableForMascot () const
std::vector< int >	getWhichAvailableForMascot2 () const
	Returns a vector of logical CPU numbers available for Mascot (or any other process).
bool	isLogicalCPUAvailableForMascot (const int cpu) const
	Returns true if the numbered logical CPU is available to Mascot (or any other process).
bool	isPrimaryLogicalProcessor (const int cpu) const
	Supersedes getHyperThreadedCPUsMask.
bool	isProcessAffinitySupported () const
	Returns true if process affinity is supported by the OS and false if only thread affinity is supported.
bool	isThreadedLogicalProcessor (const int cpu) const
	Supersedes getHyperThreadedCPUsMask.
bool	isUseProcessesNotThreads () const
	Returns a flag which indicates if the platform supports pinning threads to a processor.
bool	isValid () const
	Call this function to determine if there have been any errors.
ms_processors &	operator= (const ms_processors &right)
	Assignment operator for C++ client applications.

Detailed Description

This class is designed to retrieve current CPU configuration on the computer and set affinity.

Just create an instance and then read necessary values using other members. Check for validity (if necessary) and report any errors (if any) after reading the configuration.

In this class, a logical processsor number is a zero based contiguous index. Under Windows 7/Server 2008 R2 and later, more than 64 'cores' are supported, and in this case, they are split into processor groups, and there may be gaps in the numbering. For example, on a system with 2 x 48core processors, group 0 will have 0-47, and group 1 will have numbers 64-111.

Examples

config_procs.cpp.

Member Enumeration Documentation

anonymous enum

anonymous enum

The maximum number of cores that may be used for a single 'cpu' license.

Warning

This value should no longer be used as the number of cores per cpu is now specified in the license.

Note that the cores may be spread over multiple physical processors and that 'threaded' (e.g. hyperthreaded) units are not included

(Defined as an enum rather than static const int to support VC6)

Enumerator
DEPRECATED_MAX_CORES_PER_LICENSE	The maximum number of cores that may be used for a single 'cpu' license.

HYPERTHREADING

enum HYPERTHREADING

Hyper-threading status for the CPUs.

This is currently only relevant for Intel Pentium processors and Power 5 processors under AIX. It will be HT_NOT_CAPABLE for AMD dual processor systems.

See Using enumerated values and static const ints in Perl, Java, Python and C#.

Enumerator
HT_NOT_CAPABLE	For older Intel chips, and all other processors.
HT_ENABLED	Intel processor that supports hyper-threading and has it enabled in the BIOS.
HT_DISABLED	Pentium P4 (non Xeon) that has hyper-threading 'cobbled' so it cannot be used.
HT_SUPPORTED_NOT_ENABLED	Pentium P4 (Xeon) and later that has hyper-threading turned off in the BIOS.
HT_CANNOT_DETECT	Pentium P4, but OS limitation prevents detection of HT.

Constructor & Destructor Documentation

ms_processors()

ms_processors	(	bool	checkLinuxHT,
		int	unused
	)

Retrieves all CPU information immediately.

Parameters

checkLinuxHT	is now ignored and always assumed to be 'true'. (It was required for 2.4 kernels where detection was slow)
unused	was only used for Intel Linux when checkLinuxHT is set to false so is also now ignored.

Member Function Documentation

appendErrors()

void appendErrors ( const ms_errors &  src )

inherited

Copies all errors from another instance and appends them at the end of own list.

Parameters

src	The object to copy the errors across from. See Maintaining object references: two rules of thumb.

clearAllErrors()

void clearAllErrors ( )

inherited

Remove all errors from the current list of errors.

The list of 'errors' can include fatal errors, warning messages, information messages and different levels of debugging messages.

All messages are accumulated into a list in this object, until clearAllErrors() is called.

See Error Handling.

See also

isValid(), getLastError(), getLastErrorString(), getErrorHandler()

Examples

common_error.cpp, resfile_error.cpp, and resfile_summary.cpp.

copyFrom() [1/2]

void copyFrom ( const ms_errors *  right )

inherited

Use this member to make a copy of another instance.

Parameters

right

is the source to initialise from

copyFrom() [2/2]

void copyFrom

(

const ms_processors *

right

)

Allows to make a copy of another instance.

Called by the copy constructor in C++.

Parameters

right

pointer to a valid ms_processors object

getAutoDetectNumThreads()

int getAutoDetectNumThreads	(	const int	numLicensed,
		const int	numCoresPerCpuLicense
	)		const

Return the 'optimal' number of threads for the license.

For Mascot 2.3 up to Mascot 2.6 (inclusive), each license can be used for up to 4 cores. If the processor supports hyperthreading, then these are added 'for free'.

For Mascot 2.7 and later, the number of cores per cpu is defined in the license file, and that value will be passed to this function

The code to calculate this value is:

    int threadedFactor  = getNumLogicalPerPhysical() / getNumCores();
    int maxLicensable   = numLicensed * \a numCoresPerCpuLicense * threadedFactor;

    if (maxLicensable <= getNumAvailableToProcess()) {
        return maxLicensable;
    } else {
        return getNumAvailableToProcess();
    }

For example, consider a 6 core processor with Intel hyperthreading. The processor will have 12 'virtual cpus'. If numLicensed is 1, then this function will return 8.

If the number of threads in mascot.dat is specified as ms_databaseoptions::NUM_THREADS_AUTO_DETECT, then this function is called by nph-mascot.exe to determine the number of threads to use.

Parameters

numLicensed	is the value of the "CPU units" licence feature.
numCoresPerCpuLicense	is the value of the "Cores per CPU units" licence feature.

Returns

The number of threads that should be created.

getCoreFromLogical()

int getCoreFromLogical

(

const int

cpu

)

const

For multi-core processors, returns the core number for the give logical CPU.

If getNumCores() is 1, then this will return -1 for each CPU. Note that the core ID returned has no real significance – it is just a number. To use it, for example to see which logical IDs correspong to hyper-threading / cool threads on the same core, you need to see if one or more logical ID's have the same core ID and same physical ID, and then 'group' these together.

See also

getPhysicalFromLogical()

Parameters

cpu	is the number of the logical CPU. To test if this is a valid logical CPU number, check that the return value from isLogicalCPUAvailableForMascot() is true.

Returns

The ID of the core that corresponds to the logical CPU.

getErrorHandler()

const ms_errs * getErrorHandler ( ) const

inherited

Retrive the error object using this function to get access to all errors and error parameters.

See Error Handling.

Returns

Constant pointer to the error handler

See also

isValid(), getLastError(), getLastErrorString(), clearAllErrors(), getErrorHandler()

Examples

common_error.cpp, and http_helper_getstring.cpp.

getHT_IDFromLogical()

int getHT_IDFromLogical

(

const int

cpu

)

const

For Intel processors, return an ID corresponding to the logical processors hyper-threading state.

Only currently supported for Intel .

Note that the ID returned has no real significance – it is just a number, and will currently be either 0 or 1. To use it, for example to see which logical IDs share the same core on a CPU, you need to see if one or more logical ID's have the same core ID and same physical ID, and then 'group' these together.

See also

getPhysicalFromLogical(), getCoreFromLogical()

Parameters

cpu	is the number of the logical CPU. To test if this is a valid logical CPU number, check that the return value from isLogicalCPUAvailableForMascot() is true.

Returns

The hyper-threading ID that corresponds to the logical CPU.

getHyperThreadedCPUsMask()

UINT64 getHyperThreadedCPUsMask

(

)

const

Deprecated:

Use isPrimaryLogicalProcessor(), getCoreFromLogical() and getPhysicalFromLogical() instead.

Returns a 'mask' with the bit set for each logical CPU number that is hyper-threaded. The return value is a 64 bit integer, so the maximum number of logical cpus per system that is supported by this function will be 64.

This function is now poorly named - for HyperThreaded read HyperThreadedOrMultiCored, because it doesn't differentiate between a hyper-threaded CPU and a multi-cored CPU.

The 'primary' logical CPU for each physical CPU will not have this bit set. For example, on a dual CPU (single core) Intel system with hyper-threading enabled, the low 8 bits of this flag would be 00001100, indicating that CPU numbers 2 and 3 were the hyper-threaded ones.

The assignment of primary and secondary is totally artificial as both are generally equal.

Returns

A mask indicating which logical CPU numbers refer to 'threads' or second/subsequent cores on each physical processor.

getHyperThreadingState()

ms_processors::HYPERTHREADING getHyperThreadingState

(

)

const

Returns the hyper-threading state as best as can be detected .

See also

getMultithreadedName(), getNumPhysicalOnSystem(), getNumOnSystem(), getNumLogicalPerPhysical()

Returns

Whether the system supports some type of multi-threading.

getLastError()

int getLastError ( ) const

inherited

Return the error description of the last error that occurred.

All errors are accumulated into a list in this object, until clearAllErrors() is called. This function returns the last error that occurred.

See Error Handling.

See also

isValid(), getLastErrorString(), clearAllErrors(), getErrorHandler()

Returns

the error number of the last error, or 0 if there have been no errors.

getLastErrorString()

std::string getLastErrorString ( ) const

inherited

Return the error description of the last error that occurred.

All errors are accumulated into a list in this object, until clearAllErrors() is called. This function returns the last error that occurred.

Returns

Most recent error, warning, information or debug message

See Error Handling.

See also

isValid(), getLastError(), clearAllErrors(), getErrorHandler()

Examples

common_error.cpp, config_enzymes.cpp, config_fragrules.cpp, config_license.cpp, config_mascotdat.cpp, config_masses.cpp, config_modfile.cpp, config_procs.cpp, config_quantitation.cpp, config_taxonomy.cpp, http_helper_getstring.cpp, and tools_aahelper.cpp.

getMultithreadedName()

std::string getMultithreadedName

(

)

const

Returns a string that describes multithreading or multi-core capabilities.

• For AMD processors, this will either be "single core", "dual core", "quad core" or "xx core".

• For Intel processors, this will potentially be made up of two parts, separated by a comma. The first part specifies the hyper-threading state and will be

  • "No hyper-threading in cpu"
  • "hyper-threading enabled"
  • "hyper-threading disabled in cpu"
  • "hyper-threading disabled in bios"
  • "Cannot detect hyper-threading"

  The second part will either be "single core", "dual core", "quad core" or "xx core".

Returns

The name of the multithreading supported on the processor.

getNumAvailableToProcess()

int getNumAvailableToProcess

(

)

const

Returns the number of logical CPUs that a process can use.

On some systems with processor sets or other resource management, it is possible to prevent a user or process from having access to all of the CPUs on the system. In this case, this function will return a smaller value than getNumOnSystem. Currently, this function always returns the same value as getNumOnSystem()

See also

getNumPhysicalOnSystem(), getWhichAvailableForMascot().

Returns

The number of logical CPUs that a process can use.

getNumCores()

int getNumCores

(

const int

packageID = -1

)

const

Returns the number of cores on the processor specified by the physical CPU number.

The returned number does not include hyper-threaded CPUs. For example, for a dual core Xeon processor with hyper-threading, this function will return 2, but getNumLogicalPerPhysical() will return 4.

Parameters

packageID

is the number of the physical CPU as returned by getPhysicalFromLogical(). Prior to December 2017, all supported systems except Solaris were required to have the same number of cores on each processor, so this parameter was ignored. The default value of -1 is used to specify the physical processor ID for the first logical processor. The safe way to get this parameter is to initially find a logical cpu number using getWhichAvailableForMascot2() and then to call getPhysicalFromLogical() with this logical CPU number.

Returns

the number of cores on the specfied physical CPU.

getNumLogicalPerPhysical()

int getNumLogicalPerPhysical

(

const int

packageID = 0

)

const

Returns the number of 'logical' CPUs per physical processor.

Most processors now have multiple cores and some also provide multiple threading (known as hyper-threading).

For example, a dual core Intel processor with hyper-threading, this function will return 4.

Parameters

packageID

is the zero based number of the physical processor

Returns

The number of logical processors running on each physical processor.

getNumOnSystem()

int getNumOnSystem

(

)

const

Returns the number of logical CPUs installed in the system.

The number of logical CPUs may be different from the number of physical CPUs, for example with Intel Hyper-threading or AMD multi-core.

See also

getNumPhysicalOnSystem(), getNumAvailableToProcess(), getWhichAvailableForMascot().

Returns

The number of logical CPUs installed in the system.

Examples

config_procs.cpp.

getNumPhysicalOnSystem()

int getNumPhysicalOnSystem

(

)

const

Return the number of physical CPUs on a system.

The number of logical CPUs may be different from the number of physical CPUs, for example with Intel hyper-threading or multi-core processors.

See also

getNumOnSystem(), getNumAvailableToProcess(), getWhichAvailableForMascot().

Returns

The number of physical CPUs on a system.

getNumProcessorGroups()

int getNumProcessorGroups

(

)

const

Return the number of processor groups.

Returns

1 for Linux, and >= 1 for Windows

getPhysicalFromLogical()

int getPhysicalFromLogical

(

const int

cpu

)

const

Returns the physical CPU number for a given logical CPU number.

If getNumLogicalPerPhysical() is 1, this will return -1 for each CPU. Note that the physical ID returned has no real significance – it is just a number. To use it, need to see if one or more logical ID's have the same physical ID, and then 'group' these together.

Parameters

cpu	is the number of the logical CPU. To test if this is a valid logical CPU number, check that the return value from isLogicalCPUAvailableForMascot() is true.

Returns

The physical ID of the CPU.

getProcessorName()

std::string getProcessorName

(

)

const

Returns a string that describes the processor.

Will return an empty string or one of the following:

• Intel

• AMD

Returns

processor name

getWhichAvailableForMascot()

UINT64 getWhichAvailableForMascot

(

)

const

Deprecated:

Use isLogicalCPUAvailableForMascot() instead.

Deprecated:

Use getWhichAvailableForMascot2

Returns a 64 bit mask of the logical CPUs available to Mascot (or any other process). The return value is a 64 bit integer, so the maximum number of logical CPUs per system that is supported will be 64.

This function returns a mask of the CPUs available to Mascot. So, if the least significant bit is set, the processor 0 is available to Mascot etc. These bits indicate logical CPUs and not physical CPUs.

On some systems with processor sets or other resource management, it is possible to prevent a user or process from having access to all of the CPUs on the system. In this case, the returned mask will have 'holes'.

Returns

A 64 bit mask indicating which CPUs are online.

getWhichAvailableForMascot2()

std::vector< int > getWhichAvailableForMascot2

(

)

const

Returns a vector of logical CPU numbers available for Mascot (or any other process).

This function supersedes getWhichAvailableForMascot() which is limited to a maximum of 64 processors per system.

On some systems with processor sets or other resource management, it is possible to prevent a user or process from having access to all of the CPUs on the system, so a system with 6 cpus may not have numbers 0..5.

See also

isLogicalCPUAvailableForMascot() which may be more convenient.

Returns

A vector of the processors available for Mascot. See Using STL vector classes vectori, vectord and VectorString in Perl, Java, Python and C#.

isLogicalCPUAvailableForMascot()

bool isLogicalCPUAvailableForMascot

(

const int

cpu

)

const

Returns true if the numbered logical CPU is available to Mascot (or any other process).

See also getWhichAvailableForMascot2().

On some systems with processor sets or other resource management, it is possible to prevent a user or process from having access to all of the CPUs on the system, so a system with 6 CPUs may not have numbers 0..5.

Parameters

cpu	is the logical CPU number

Returns

True if the numbered logical CPU is available to Mascot (or any other process).

isPrimaryLogicalProcessor()

bool isPrimaryLogicalProcessor

(

const int

cpu

)

const

Supersedes getHyperThreadedCPUsMask.

The 'primary' logical CPU for each physical CPU is the first logical CPU for each physical CPU. Subsequent cores/threading logical CPUs on the same physical processor will return false from this function.

The Mascot Database status screen lists non 'primary' processors in italics.

Parameters

cpu	is the number of the logical CPU. To test if this is a valid logical CPU number, check that the return value from isLogicalCPUAvailableForMascot() is true.

Returns

False for each logical CPU numbers which is a second of subsequent core or 'thread'.

isProcessAffinitySupported()

bool isProcessAffinitySupported

(

)

const

Returns true if process affinity is supported by the OS and false if only thread affinity is supported.

Mascot Server uses process affinity where possible.

For Linux, this always returns true.

For Microsoft Windows, this returns true if there is only one processor set, otherwise it returns false.

Returns

True if process affinity is supported by the OS and false if only thread affinity is supported.

isThreadedLogicalProcessor()

bool isThreadedLogicalProcessor

(

const int

cpu

)

const

Supersedes getHyperThreadedCPUsMask.

The 'primary' logical cpu for each physical CPU is the first logical cpu for each physical CPU. Subsequent logical CPUs that are on the same core on the same physical processors as a previous logical CPU are described by Mascot Parser as 'threaded', and will return true from this function.

Parameters

cpu	is the number of the logical CPU. To test if this is a valid logical CPU number, check that the return value from isLogicalCPUAvailableForMascot() is true.

Returns

the opposite of isPrimaryLogicalProcessor().

isUseProcessesNotThreads()

bool isUseProcessesNotThreads

(

)

const

Returns a flag which indicates if the platform supports pinning threads to a processor.

Now returns false for all platforms because all platforms support POSIX threads.

Returns

Will always return false.

isValid()

bool isValid ( ) const

inherited

Call this function to determine if there have been any errors.

This will return true unless there have been any fatal errors.

See Error Handling.

Returns

True if no fatal error occured

See also

getLastError(), getLastErrorString(), clearAllErrors(), getErrorHandler()

Examples

common_error.cpp, config_enzymes.cpp, config_fragrules.cpp, config_license.cpp, config_mascotdat.cpp, config_masses.cpp, config_modfile.cpp, config_procs.cpp, config_quantitation.cpp, config_taxonomy.cpp, http_helper_getstring.cpp, peptide_list.cpp, repeat_search.cpp, resfile_error.cpp, resfile_info.cpp, resfile_input.cpp, resfile_params.cpp, resfile_summary.cpp, and tools_aahelper.cpp.

---

The documentation for this class was generated from the following files:

• ms_processors.hpp
• ms_processors.cpp