Matrix Science header
Public Types | Public Member Functions

ms_processors Class Reference
[Mascot configuration files module]

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:
Inheritance graph
[legend]
Collaboration diagram for ms_processors:
Collaboration graph
[legend]

List of all members.

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_processors *right)
 Allows to make a copy of another instance.
void copyFrom (const ms_errors *right)
 Use this member 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_errsgetErrorHandler () 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_processorsoperator= (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

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.

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 ( bool  checkLinuxHT,
int  unused 
)

Retrieves all CPU information immediately.

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

Member Function Documentation

void appendErrors ( const ms_errors src ) [inherited]

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

Parameters:
srcThe object to copy the errors across from. See Maintaining object references: two rules of thumb.
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.
void copyFrom ( const ms_processors right )

Allows to make a copy of another instance.

Called by the copy constructor in C++.

Parameters:
rightpointer to a valid ms_processors object
void copyFrom ( const ms_errors right ) [inherited]

Use this member to make a copy of another instance.

Parameters:
rightis the source to initialise from
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:
numLicensedis the value of the "CPU units" licence feature.
numCoresPerCpuLicenseis the value of the "Cores per CPU units" licence feature.
Returns:
The number of threads that should be created.
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:
cpuis 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.
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.
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:
cpuis 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.
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.
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.
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.

Reimplemented in ms_mascotresfile.

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()

Reimplemented in ms_mascotresfile.

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.
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.
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.
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:
packageIDis 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.
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:
packageIDis the zero based number of the physical processor
Returns:
The number of logical processors running on each physical processor.
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.
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.
int getNumProcessorGroups (  ) const

Return the number of processor groups.

Returns:
1 for Linux, and >= 1 for Windows
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:
cpuis 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.
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
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.
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#.
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:
cpuis the logical CPU number
Returns:
True if the numbered logical CPU is available to Mascot (or any other process).
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:
cpuis 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'.
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.
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:
cpuis 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().
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.
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, resfile_summary.cpp, and tools_aahelper.cpp.

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

Copyright © 2022 Matrix Science Ltd.  All Rights Reserved. Generated on Thu Mar 31 2022 01:12:36