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. 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  { 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 numLicensed)
 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.
void defaultValues ()
 Call this function to re-initialise the object.
unsigned char GetAPIC_ID (unsigned char &logical_id, unsigned char &physical_id, unsigned char &core_id, unsigned char &ht_id)
int getAutoDetectNumThreads (const int numLicensed) 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 cpu=-1) const
 Returns the number of cores on the processor specified by the physical CPU number.
int getNumLogicalPerPhysical () 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 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 ()
 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.

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.

Examples:

config_procs.cpp.


Member Enumeration Documentation

anonymous enum

The maximum number of cores that may be used for a single 'cpu' 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:
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 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  numLicensed 
)

Retrieves all CPU information immediately.

Parameters:
checkLinuxHTFor Intel Linux, it is really hard to get hyper-threading information in a timely manner when running on a 2.4 kernel because it is necessary to run multiple threads and just wait until one thread has run a CPUID instruction on each CPU. For a 2.6 or later kernel, it's possible to force the process to run on a particular CPU, so this is fast. For this reason, this flag is only set to true when ms-monitor.exe and ms-mascotnode.exe start up. This flag is also used for SMT detection under AIX because it is only possible to detect SMT when running as root. This means that under AIX on a Power5 system, ms-monitor and ms-mascotnode.exe must be run as root. Under AIX Power 5 and later, a 'hidden' file ../data/.smt is created when this function is run with this parameter set to true. When this parameter is set to false, the same file is read.
numLicensedis only used for Intel Linux when checkLinuxHT is set to false and it is a 2.4 kernel. In this case, the code is very specific to Mascot and it is assumed that if numLicensed_ < number of logical CPUs, then hyper-threading must be enabled. (The reason is that if ms-monitor.exe or ms-mascotnode.exe have started, then there must be sufficient licenses for the number of physical cpus. When nph-mascot.exe or ms-status.exe call this function (with checkLinuxHT set to false), they have already checked that ms-monitor.exe is running.

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

Call this function to re-initialise the object.

This function is called by the constructor and can take a little time to run on some systems if it is hard to determine processor information.

unsigned char GetAPIC_ID ( unsigned char &  logical_id,
unsigned char &  physical_id,
unsigned char &  core_id,
unsigned char &  ht_id 
)

Returns the APIC value for the current processor. Also, sets the logical and physical values for this processor. Under Windows, this will be called for each CPU. Under Linux, it's pot luck as to which one it gets set for. The term logical_id has little meaning here.

Parameters:
logical_idreference which will be set
physical_idreference which will be set
core_idreference which will be set
ht_idreference which will be set
Returns:
APIC id
int getAutoDetectNumThreads ( const int  numLicensed ) const

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

For Mascot 2.3 and later, each license can be used for up to ms_processors::MAX_CORES_PER_LICENSE cores. If the processor supports hyperthreading, then these are added 'for free'.

The code to calculate this value is:

    int threadedFactor  = getNumLogicalPerPhysical() / getNumCores();
    int maxLicensable   = numLicensed * MAX_CORES_PER_LICENSE * 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.
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.

Only currently supported for Solaris and Intel/AMD.

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 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 .

For all processors apart from 32/64 bit Intel/AMD systems, AIX Power 5 and later Sun UltraSPARC systems, this will return HT_NOT_CAPABLE.

For UltraSPARC and Power systems, the term is not strictly hyper-threading but SMT, CMT or Cool threads.

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".
  • For Sun systems, this will return CMT (for UltraSparc IV+) and CoolThreads for T1/T2.
  • For Power systems with SMT support, this will return SMT.
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.

See also:
getNumPhysicalOnSystem(), getWhichAvailableForMascot().
Returns:
The number of logical CPUs that a process can use.
int getNumCores ( const int  cpu = -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:
cpuis the number of the physical CPU as returned by getPhysicalFromLogical(). Currently (May 2008), all supported systems except Solaris must have the same number of cores on each processor, so this parameteris ignored. The default value of -1 is used to specify the physical processor ID for the first logical processor. In future releases, the safe way to get this parameter will be 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

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

Many processors now have multiple cores and some also provide multiple threading (known as hyper-threading, cool threads, SMT etc.).

For other processors, this will return 1. This information is subject to change as more processors become multi-core.

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

Returns:
The number of logical processors running on each physical processor.
int getNumOnSystem (  ) const

Returns the number of logical CPUs installed in the system.

Note that the number of logical CPUs may be different from the number of physical CPUs, for example with Intel Hyper-threading or multi-core or the Ultra Sparc IV processors.

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, multi-core or Ultra Sparc IV processors. Mascot is licensed by the number of physical processors (or sockets).

See also:
getNumOnSystem(), getNumAvailableToProcess(), getWhichAvailableForMascot().
Returns:
The number of physical CPUs on a system.
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
  • Power
  • MIPS
  • Alpha
  • UltraSparc III
  • UltraSparc-IV
  • UltraSparc T1
  • UltraSparc T2
  • sparcv9
Returns:
processor name
UINT64 getWhichAvailableForMascot (  ) const
Deprecated:
Use isLogicalCPUAvailableForMascot() instead.

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

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 classes 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 CPU number, which would normally be a positive integer.
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 uses process affinity where possible.

Microsoft Windows and Linux kernels 2.6 and later are currently the only operating systems for which this function returns true.

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.

Only properly supported on Solaris.

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.

For example, on a T1 processor, there are four cool threads per core, so this function would return true for the last 3 of the cool threads for each of the 8 cores.

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:
True for each logical CPU numbers which is a second or later for a particular core on a particular physical processor.
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 is 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 © 2016 Matrix Science Ltd.  All Rights Reserved. Generated on Fri Jun 2 2017 01:44:53