Gromacs
5.1.4
|
Provides low-level utilities for error handling and other tasks.
This module provides various low-level utilities for tasks such as error handling and string formatting, as well as helper classes and common custom containers to simplify implementation of other code. Contents of the module are discussed in more details under the different headings below. Some of the code in installed headers in the module is intended for use directly from code outside the Gromacs library, but a significant portion is exposed only because other public headers depend on it.
Since this module implements error handling, it should be at the lowest level: it should not depend on other modules. Any functionality needed by the error handling code should also be kept in this module.
Exception classes used in the library are declared in the exceptions.h header file. Most Gromacs-specific exceptions derive from gmx::GromacsException.
This header also declares a GMX_THROW macro that should be used for throwing exceptions. GMX_THROW_WITH_ERRNO is also provided for reporting syscall errors, but its use should be mostly limited to within the library. This header also declares helper functions printFatalErrorMessage(), formatExceptionMessageToString(), formatExceptionMessageToFile(), and translateException() for creating standard error messages and translating exceptions to error return codes. processExceptionAtExit() provides clean-up code before exiting the program after an exception. To help in cases where bottom-up conversion to C++ is appropriate, macro GMX_CATCH_ALL_AND_EXIT_WITH_FATAL_ERROR is also provided to catch all exceptions at C++ to C boundary.
Use of error return codes should be avoided in new code except in C wrappers and similar, but to ease migration (and for these cases where they are necessary), facilities for handling them are provided by the errorcodes.h header file. It provides a set of error codes (the enum gmx::ErrorCode) that should be used for return codes in functions. It also provides macros GMX_ERROR and GMX_ERROR_NORET that should be used for returning an error code. setFatalErrorHandler() is provided to alter the behavior of GMX_ERROR and GMX_ERROR_NORET. The default handler prints the reason of the error to stderr
and aborts the execution.
Header file gmxassert.h is also provided for assertions. It declares macros GMX_ASSERT and GMX_RELEASE_ASSERT that should be used for assertions.
The header file.h declares a gmx::File class for basic I/O support.
The header path.h declares helpers for manipulating paths and for managing directories.
The fate of these headers depends on what is decided in Redmine issue #950.
The header basedefinitions.h contains common definitions and macros used throughout GROMACS. It includes fixed-width integer types (gmx_int64_t
and friends), gmx_bool
for C code, some macros for compiler-specific attributes, and GMX_UNUSED_VALUE and GMX_IGNORE_RETURN_VALUE for handling warnings about unused values.
The header classhelpers.h implements a gmx::PrivateImplPointer template for easily writing classes that use the private implementation idiom. This header also declares GMX_DISALLOW_COPY_AND_ASSIGN and GMX_DISALLOW_ASSIGN macros for class declarations.
The header flags.h implements a gmx::FlagsTemplate template for better type safety when using bit flag fields.
The header init.h declares gmx::init() and gmx::finalize() for initializing and deinitializing the GROMACS library.
The header arrayref.h implements a gmx::ConstArrayRef class for exposing a C array or part of a std::vector (basically, any continuous stretch of memory) throuh a std::vector-like interface.
The header stringutil.h declares various string utility routines.
The header gmxmpi.h abstracts away the mechanism of including either MPI or thread-MPI headers depending on compilation options. Similarly, gmxomp.h removes the need to use conditional compilation for code that needs to include omp.h for OpenMP functions.
The header gmxregex.h declares gmx::Regex and regexMatch() for basic regular expression matching using an interface similar to C++11.
The header messagestringcollector.h declares a gmx::MessageStringCollector class for composing messages with context information.
The header sysinfo.h declares gmx_getpid() for getting the current process id.
The header programcontext.h declares a gmx::ProgramContextInterface that is used to initialize and access information about the running program, such as the name and path of the executable. This information is used, e.g., by the error handling code in formatting standard error messages.
The header qsort_threadsafe.h provides a guaranteed threadsafe implementation for qsort().
The header uniqueptr.h declares gmx::gmx_unique_ptr, which is intended for declaring smart pointer types with unique ownership.
Classes | |
class | gmx::ArrayRef< T > |
STL-like container for an interface to a C array (or part of a std::vector). More... | |
class | gmx::ConstArrayRef< T > |
STL-like container for non-mutable interface to a C array (or part of a std::vector). More... | |
class | gmx::PrivateImplPointer< Impl > |
Helper class to manage a pointer to a private implementation class. More... | |
class | gmx::DataFileOptions |
Search parameters for DataFileFinder. More... | |
struct | gmx::DataFileInfo |
Information about a data file found by DataFileFinder::enumerateFiles(). More... | |
class | gmx::DataFileFinder |
Searches data files from a set of paths. More... | |
class | gmx::DirectoryEnumerator |
Lists files in a directory. More... | |
class | gmx::ExceptionInitializer |
Provides information for Gromacs exception constructors. More... | |
class | gmx::GromacsException |
Base class for all exception objects in Gromacs. More... | |
class | gmx::FileIOError |
Exception class for file I/O errors. More... | |
class | gmx::UserInputError |
Exception class for user input errors. More... | |
class | gmx::InvalidInputError |
Exception class for situations where user input cannot be parsed/understood. More... | |
class | gmx::InconsistentInputError |
Exception class for situations where user input is inconsistent. More... | |
class | gmx::SimulationInstabilityError |
Exception class for simulation instabilities. More... | |
class | gmx::InternalError |
Exception class for internal errors. More... | |
class | gmx::APIError |
Exception class for incorrect use of an API. More... | |
class | gmx::NotImplementedError |
Exception class for use of an unimplemented feature. More... | |
class | gmx::FileInitializer |
Parameters for creating a File object. More... | |
class | gmx::File |
Basic file object. More... | |
class | gmx::FileInputRedirectorInterface |
Allows overriding file existence checks from code that supports it. More... | |
class | gmx::FileOutputRedirectorInterface |
Allows capturing stdout and file output from code that supports it. More... | |
class | gmx::FlagsTemplate< FlagType > |
Template class for typesafe handling of combination of flags. More... | |
class | gmx::Regex |
Represents a regular expression. More... | |
class | gmx::MessageStringCollector |
Helper class for collecting message strings, optionally with context. More... | |
class | gmx::MessageStringContext |
Convenience class for creating a message context. More... | |
struct | gmx::InstallationPrefixInfo |
Provides information about installation prefix (see ProgramContextInterface::installationPrefix()). More... | |
class | gmx::ProgramContextInterface |
Provides context information about the program that is calling the library. More... | |
class | gmx::scoped_cptr< T, D > |
Stripped-down version of scoped_ptr that uses sfree() or custom deleter. More... | |
class | gmx::StringFormatter |
Function object that wraps a call to formatString() that expects a single conversion argument, for use with algorithms. More... | |
class | gmx::IdentityFormatter |
Function object to implement the same interface as StringFormatter to use with strings that should not be formatted further. More... | |
class | gmx::TextLineWrapperSettings |
Stores settings for line wrapping. More... | |
class | gmx::TextLineWrapper |
Wraps lines to a predefined length. More... | |
class | gmx::gmx_unique_ptr< T > |
Smart pointer for unique ownership. More... | |
Macros | |
#define | GMX_UNUSED_VALUE(value) (void)value |
Macro to explicitly ignore an unused value. | |
#define | GMX_IGNORE_RETURN_VALUE(call) ::gmx::internal::ignoreValueHelper(call) |
Macro to explicitly ignore a return value of a call. More... | |
#define | GMX_DISALLOW_COPY_AND_ASSIGN(ClassName) |
Macro to declare a class non-copyable and non-assignable. More... | |
#define | GMX_DISALLOW_ASSIGN(ClassName) |
Macro to declare a class non-assignable. More... | |
#define | GMX_ERROR(retcode, msg) |
Macro for raising an error and returning from a function. More... | |
#define | GMX_ERROR_NORET(retcode, msg) ::gmx::internal::fatalError(retcode, msg, __FILE__, __LINE__) |
Macro for raising an error in a function that does not return int . More... | |
#define | GMX_THROW(e) BOOST_THROW_EXCEPTION((e)) |
Macro for throwing an exception. More... | |
#define | GMX_THROW_WITH_ERRNO(e, syscall, err) |
Macro for throwing an exception based on errno. More... | |
#define | GMX_CATCH_ALL_AND_EXIT_WITH_FATAL_ERROR |
Macro for catching exceptions at C++ -> C boundary. More... | |
#define | GMX_RELEASE_ASSERT(condition, msg) |
Macro for asserts that should also be present in the release version. More... | |
#define | GMX_ASSERT(condition, msg) GMX_RELEASE_ASSERT(condition, msg) |
Macro for debug asserts. More... | |
#define | gmx_qsort_threadsafe qsort |
Threadsafe qsort(). More... | |
Typedefs | |
typedef void(* | gmx::ErrorHandlerFunc )(int retcode, const char *msg, const char *file, int line) |
Callback function pointer type for error handlers. More... | |
Enumerations | |
enum | gmx::ErrorCode { gmx::eeOK, gmx::eeOutOfMemory, gmx::eeFileNotFound, gmx::eeFileIO, gmx::eeInvalidInput, gmx::eeInconsistentInput, gmx::eeInstability, gmx::eeNotImplemented, gmx::eeInvalidValue, gmx::eeInvalidCall, gmx::eeInternalError, gmx::eeAPIError, gmx::eeRange, gmx::eeCommunication, gmx::eeUnknownError } |
Possible error return codes from Gromacs functions. More... | |
Functions | |
template<typename T > | |
void | gmx::swap (ArrayRef< T > &a, ArrayRef< T > &b) |
Simple swap method for ArrayRef objects. More... | |
template<typename T > | |
void | gmx::swap (ConstArrayRef< T > &a, ConstArrayRef< T > &b) |
Simple swap method for ConstArrayRef objects. More... | |
const char * | gmx_version (void) |
Version string, containing the version, date, and abbreviated hash. More... | |
const char * | gmx_version_git_full_hash (void) |
Full git hash of the latest commit. More... | |
const char * | gmx_version_git_central_base_hash (void) |
Full git hash of the latest commit in a central GROMACS repository. More... | |
const char * | gmx::getErrorCodeString (int errorcode) |
Returns a short string description of an error code. More... | |
ErrorHandlerFunc | gmx::setFatalErrorHandler (ErrorHandlerFunc handler) |
Sets callback function for handling errors. More... | |
void | gmx::printFatalErrorMessage (FILE *fp, const std::exception &ex) |
Formats a standard fatal error message for reporting an exception. More... | |
std::string | gmx::formatExceptionMessageToString (const std::exception &ex) |
Formats an error message for reporting an exception. More... | |
void | gmx::formatExceptionMessageToFile (FILE *fp, const std::exception &ex) |
Formats an error message for reporting an exception. More... | |
int | gmx::processExceptionAtExit (const std::exception &ex) |
Handles an exception that is causing the program to terminate. More... | |
int | gmx::translateException (const std::exception &ex) |
Converts an exception into a return code. | |
FileInputRedirectorInterface & | gmx::defaultFileInputRedirector () |
Returns default implementation for FileInputRedirectorInterface. More... | |
FileOutputRedirectorInterface & | gmx::defaultFileOutputRedirector () |
Returns default implementation for FileOutputRedirectorInterface. More... | |
const DataFileFinder & | gmx::getLibraryFileFinder () |
Gets a finder for locating data files from share/top/. More... | |
int | gmx_omp_get_max_threads (void) |
Returns an integer equal to or greater than the number of threads that would be available if a parallel region without num_threads were defined at that point in the code. More... | |
int | gmx_omp_get_num_procs (void) |
Returns the number of processors available when the function is called. More... | |
int | gmx_omp_get_thread_num (void) |
Returns the thread number of the thread executing within its thread team. More... | |
void | gmx_omp_set_num_threads (int num_threads) |
Sets the number of threads in subsequent parallel regions, unless overridden by a num_threads clause. More... | |
gmx_bool | gmx_omp_check_thread_affinity (char **message) |
Check for externally set thread affinity to avoid conflicts with GROMACS internal setting. More... | |
static void | gmx_pause () |
Pause for use in a spin-wait loop. | |
bool | gmx::regexMatch (const char *str, const Regex ®ex) |
Matches a string with a regular expression. More... | |
void | gmx::init (int *argc, char ***argv) |
Initializes the GROMACS library. More... | |
void | gmx::finalize () |
Deinitializes the GROMACS library. More... | |
const ProgramContextInterface & | gmx::getProgramContext () |
Returns the global ProgramContextInterface instance. More... | |
void | gmx::setProgramContext (const ProgramContextInterface *context) |
Sets the global ProgramContextInterface instance. More... | |
void | gmx_qsort (void *base, size_t nmemb, size_t size, int(*compar)(const void *, const void *)) |
Portable threadsafe sort routine. More... | |
bool | gmx::isNullOrEmpty (const char *str) |
Tests whether a string is null or empty. More... | |
bool | gmx::startsWith (const std::string &str, const std::string &prefix) |
Tests whether a string starts with another string. More... | |
bool | gmx::startsWith (const char *str, const char *prefix) |
Tests whether a string starts with another string. More... | |
bool | gmx::endsWith (const std::string &str, const char *suffix) |
Tests whether a string ends with another string. More... | |
static bool | gmx::endsWith (const std::string &str, const std::string &suffix) |
Tests whether a string ends with another string. More... | |
static bool | gmx::contains (const std::string &str, const char *substr) |
Tests whether a string contains another as a substring. More... | |
static bool | gmx::contains (const std::string &str, const std::string &substr) |
Tests whether a string contains another as a substring. More... | |
std::string | gmx::stripSuffixIfPresent (const std::string &str, const char *suffix) |
Removes a suffix from a string. More... | |
std::string | gmx::stripString (const std::string &str) |
Removes leading and trailing whitespace from a string. More... | |
std::string | gmx::formatString (const char *fmt,...) |
Formats a string (snprintf() wrapper). More... | |
template<typename InputIterator , typename FormatterType > | |
std::string | gmx::formatAndJoin (InputIterator begin, InputIterator end, const char *separator, const FormatterType &formatter) |
Formats all the range as strings, and then joins them with a separator in between. More... | |
template<typename ContainerType , typename FormatterType > | |
std::string | gmx::formatAndJoin (const ContainerType &container, const char *separator, const FormatterType &formatter) |
Formats all elements of the container as strings, and then joins them with a separator in between. More... | |
template<typename InputIterator > | |
std::string | gmx::joinStrings (InputIterator begin, InputIterator end, const char *separator) |
Joins strings from a range with a separator in between. More... | |
template<typename ContainerType > | |
std::string | gmx::joinStrings (const ContainerType &container, const char *separator) |
Joins strings from a container with a separator in between. More... | |
template<size_t count> | |
std::string | gmx::joinStrings (const char *const (&array)[count], const char *separator) |
Joins strings from an array with a separator in between. More... | |
std::vector< std::string > | gmx::splitString (const std::string &str) |
Splits a string to whitespace separated tokens. More... | |
std::string | gmx::replaceAll (const std::string &input, const char *from, const char *to) |
Replace all occurrences of a string with another string. More... | |
std::string | gmx::replaceAll (const std::string &input, const std::string &from, const std::string &to) |
Replace all occurrences of a string with another string. More... | |
std::string | gmx::replaceAllWords (const std::string &input, const char *from, const char *to) |
Replace whole words with others. More... | |
std::string | gmx::replaceAllWords (const std::string &input, const std::string &from, const std::string &to) |
Replace whole words with others. More... | |
int | gmx_gethostname (char *buf, size_t len) |
Gets the hostname as given by gethostname(), if available. More... | |
int | gmx_getpid (void) |
Returns the process ID of the current process. More... | |
int | gmx_getuid (void) |
Returns the current user ID, or -1 if not available. More... | |
int | gmx_getusername (char *buf, size_t len) |
Gets the current user name, if available. More... | |
char * | gmx_ctime_r (const time_t *clock, char *buf, size_t len) |
Portable version of ctime_r. More... | |
void | gmx_format_current_time (char *buf, size_t len) |
Gets the current time as a string. More... | |
int | gmx_set_nice (int level) |
Wrapper for nice(). More... | |
Directories | |
directory | utility |
Low-Level Utilities (utility) | |
directory | tests |
Unit tests for Low-Level Utilities (utility). | |
Files | |
file | arrayref.h |
Declares gmx::ArrayRef and gmx::ConstArrayRef. | |
file | basedefinitions.h |
Basic types and macros used throughout GROMACS. | |
file | basenetwork.h |
Utility functions for basic MPI and network functionality. | |
file | baseversion.h |
Declares functions to get basic version information. | |
file | bitmask.h |
Declares gmx_bitmask_t and associated functions. | |
file | classhelpers.h |
Declares common utility classes and macros. | |
file | cstringutil.h |
Generic C string handling functions. | |
file | datafilefinder.h |
Declares gmx::DataFileFinder and related classes. | |
file | dir_separator.h |
Provides OS-specific directory-name separator. | |
file | directoryenumerator.h |
Declares gmx::DirectoryEnumerator. | |
file | errorcodes.h |
Declares error codes and related functions for fatal error handling. | |
file | exceptions.h |
Declares common exception classes and macros for fatal error handling. | |
file | fatalerror.h |
Declares fatal error handling and debugging routines for C code. | |
file | file.h |
Declares gmx::File. | |
file | fileredirector.h |
Declares gmx::FileOutputRedirectorInterface. | |
file | flags.h |
Declares gmx::FlagsTemplate. | |
file | futil.h |
Low-level wrappers for OS-specific file handling with some GROMACS customizations. | |
file | gmxassert.h |
Defines assert macros customized for Gromacs. | |
file | gmxmpi.h |
Wraps <mpi.h> usage in Gromacs. | |
file | gmxomp.h |
Declares OpenMP wrappers to avoid conditional compilation. | |
file | gmxregex.h |
Declares simple wrapper for regular expression functionality. | |
file | init.h |
Declares functions for initializing the GROMACS library. | |
file | path.h |
Declares functions for OS-independent path handling. | |
file | programcontext.h |
Declares gmx::ProgramContextInterface and related methods. | |
file | qsort_threadsafe.h |
Portable implementation of threadsafe quicksort. | |
file | real.h |
Declares real and related constants. | |
file | scoped_cptr.h |
Declares gmx::scoped_cptr and gmx::scoped_guard_sfree. | |
file | smalloc.h |
C memory allocation routines for GROMACS. | |
file | snprintf.h |
Provide snprintf symbol on all OS (for internal Gromacs use) | |
file | stringutil.h |
Declares common string utility and formatting routines. | |
file | sysinfo.h |
Declares functions for obtaining information about the operating environment and the current process. | |
file | uniqueptr.h |
Declares gmx::gmx_unique_ptr and supporting functionality. | |
file | utility.h |
Public API convenience header for low-level utilities. | |
#define GMX_ASSERT | ( | condition, | |
msg | |||
) | GMX_RELEASE_ASSERT(condition, msg) |
Macro for debug asserts.
If NDEBUG is defined, this macro expands to nothing. If it is not defined, it will work exactly like GMX_RELEASE_ASSERT.
#define GMX_CATCH_ALL_AND_EXIT_WITH_FATAL_ERROR |
Macro for catching exceptions at C++ -> C boundary.
This macro is intended for uniform handling of exceptions when C++ code is called from C code within Gromacs. Since most existing code is written using the assumption that fatal errors terminate the program, this macro implements this behavior for exceptions. It should only be used in cases where the error cannot be propagated upwards using return values or such.
Having this as a macro instead of having the same code in each place makes it easy to 1) find all such locations in the code, and 2) change the exact behavior if needed.
Usage:
#define GMX_DISALLOW_ASSIGN | ( | ClassName | ) |
Macro to declare a class non-assignable.
For consistency, should appear last in the class declaration.
#define GMX_DISALLOW_COPY_AND_ASSIGN | ( | ClassName | ) |
Macro to declare a class non-copyable and non-assignable.
For consistency, should appear last in the class declaration.
#define GMX_ERROR | ( | retcode, | |
msg | |||
) |
Macro for raising an error and returning from a function.
The function should return int
. If it doesn't, use GMX_ERROR_NORET.
#define GMX_ERROR_NORET | ( | retcode, | |
msg | |||
) | ::gmx::internal::fatalError(retcode, msg, __FILE__, __LINE__) |
Macro for raising an error in a function that does not return int
.
#define GMX_IGNORE_RETURN_VALUE | ( | call | ) | ::gmx::internal::ignoreValueHelper(call) |
Macro to explicitly ignore a return value of a call.
Mainly meant for ignoring values of functions declared with __attribute__((warn_unused_return))
. Makes it easy to find those places if they need to be fixed, and document the intent in cases where the return value really can be ignored. It also makes it easy to adapt the approach so that they don't produce warnings. A cast to void doesn't remove the warning in gcc, while adding a dummy variable can cause warnings about an unused variable.
#define gmx_qsort_threadsafe qsort |
Threadsafe qsort().
Expands to gmx_qsort() if Gromacs is built with threading, or system qsort() otherwise.
#define GMX_RELEASE_ASSERT | ( | condition, | |
msg | |||
) |
Macro for asserts that should also be present in the release version.
Regardless of NDEBUG, this macro checks condition
, and if it is not true, it calls the assert handler.
Although this macro currently calls abort() if the assertion fails, it should only be used in a context where it is safe to throw an exception to keep the option open.
#define GMX_THROW | ( | e | ) | BOOST_THROW_EXCEPTION((e)) |
Macro for throwing an exception.
[in] | e | Exception object to throw. |
Using this macro instead of throw
directly makes it possible to uniformly attach information into the exception objects. e
should evaluate to an instance of an object derived from GromacsException.
Basic usage:
#define GMX_THROW_WITH_ERRNO | ( | e, | |
syscall, | |||
err | |||
) |
Macro for throwing an exception based on errno.
[in] | e | Exception object to throw. |
[in] | syscall | Name of the syscall that returned the error. |
[in] | err | errno value returned by the syscall. |
This macro provides a convenience interface for throwing an exception to report an error based on a errno value. In addition to adding the necessary information to the exception object, the macro also ensures that errno
is evaluated before, e.g., the constructor of e
may call other functions that could overwrite the errno value. e
should evaluate to an instance of an object derived from GromacsException.
Typical usage (note that gmx::File wraps this particular case):
typedef void(* gmx::ErrorHandlerFunc)(int retcode, const char *msg, const char *file, int line) |
Callback function pointer type for error handlers.
[in] | retcode | Code of the error that has occurred. |
[in] | msg | More detailed description of the error. |
[in] | file | Name of the file where the error occurred. |
[in] | line | Line in file on which the error occurred. |
enum gmx::ErrorCode |
Possible error return codes from Gromacs functions.
|
inlinestatic |
Tests whether a string contains another as a substring.
[in] | str | String to process. |
[in] | substr | Substring to find. |
str
contains substr
.Does not throw.
|
inlinestatic |
Tests whether a string contains another as a substring.
[in] | str | String to process. |
[in] | substr | Substring to find. |
str
contains substr
.Does not throw.
FileInputRedirectorInterface & gmx::defaultFileInputRedirector | ( | ) |
Returns default implementation for FileInputRedirectorInterface.
The returned implementation does not redirect anything, but just uses the file system normally.
Does not throw.
FileOutputRedirectorInterface & gmx::defaultFileOutputRedirector | ( | ) |
Returns default implementation for FileOutputRedirectorInterface.
The returned implementation does not redirect anything, but just opens the files at requested locations.
Does not throw.
bool gmx::endsWith | ( | const std::string & | str, |
const char * | suffix | ||
) |
Tests whether a string ends with another string.
[in] | str | String to process. |
[in] | suffix | Suffix to find. |
str
ends with suffix
.Returns true if suffix
is NULL or empty. Does not throw.
|
inlinestatic |
Tests whether a string ends with another string.
[in] | str | String to process. |
[in] | suffix | Suffix to find. |
str
ends with suffix
.Returns true if suffix
is NULL or empty. Does not throw.
void gmx::finalize | ( | ) |
Deinitializes the GROMACS library.
Decrements the initialization counter, and calls MPI_Finalize() if GROMACS is compiled with MPI support and the counter has reached zero. In that case, it is not possible to reinitialize GROMACS after calling this function. Instead, call gmx::init() at a higher level, and note that calls to init can be nested safely.
std::string gmx::formatAndJoin | ( | InputIterator | begin, |
InputIterator | end, | ||
const char * | separator, | ||
const FormatterType & | formatter | ||
) |
Formats all the range as strings, and then joins them with a separator in between.
[in] | begin | Iterator the beginning of the range to join. |
[in] | end | Iterator the end of the range to join. |
[in] | separator | String to put in between the joined strings. |
[in] | formatter | Function object to format the objects in container as strings |
begin
to end
formatted as strings and concatenated with separator
between each pair. std::bad_alloc | if out of memory. |
std::string gmx::formatAndJoin | ( | const ContainerType & | container, |
const char * | separator, | ||
const FormatterType & | formatter | ||
) |
Formats all elements of the container as strings, and then joins them with a separator in between.
[in] | container | Objects to join. |
[in] | separator | String to put in between the joined strings. |
[in] | formatter | Function object to format the objects in container as strings |
container
formatted as strings and concatenated with separator
between each pair. std::bad_alloc | if out of memory. |
void gmx::formatExceptionMessageToFile | ( | FILE * | fp, |
const std::exception & | ex | ||
) |
Formats an error message for reporting an exception.
fp | File to write the message to. | |
[in] | ex | Exception to format. |
std::bad_alloc | if out of memory. |
std::string gmx::formatExceptionMessageToString | ( | const std::exception & | ex | ) |
Formats an error message for reporting an exception.
[in] | ex | Exception to format. |
ex
. std::bad_alloc | if out of memory. |
std::string gmx::formatString | ( | const char * | fmt, |
... | |||
) |
Formats a string (snprintf() wrapper).
std::bad_alloc | if out of memory. |
This function works like sprintf(), except that it returns an std::string instead of requiring a preallocated buffer. Arbitrary length output is supported.
const char * gmx::getErrorCodeString | ( | int | errorcode | ) |
Returns a short string description of an error code.
[in] | errorcode | Error code to retrieve the string for. |
errorcode
.If errorcode
is not one of those defined for gmx::ErrorCode, the string corresponding to eeUnknownError is returned.
This function does not throw.
const DataFileFinder & gmx::getLibraryFileFinder | ( | ) |
Gets a finder for locating data files from share/top/.
If setLibraryFileFinder() has not been called (or a NULL
finder has been set), a default finder is returned. The default finder searches data files from the directory identified by the global program context; it does not respect GMXLIB environment variable. Calling initForCommandLine() sets a finder that respects GMXLIB.
Does not throw.
See setLibraryFileFinder() for thread safety.
const ProgramContextInterface & gmx::getProgramContext | ( | ) |
Returns the global ProgramContextInterface instance.
If nothing has been set with setProgramContext(), returns a default implementation that returns "GROMACS"
for the program and display names, and empty strings for other values. The default implementation never throws.
Does not throw.
See setProgramContext() for thread safety notes. You should not call this method in global deinitialization methods (e.g., destructors of global variables), since it is very difficult to clean up the state correctly in the presence of such calls. For example, initForCommandLine() assumes that such calls do not exist to be able to free the context before exiting.
char* gmx_ctime_r | ( | const time_t * | clock, |
char * | buf, | ||
size_t | len | ||
) |
Portable version of ctime_r.
Does not throw.
void gmx_format_current_time | ( | char * | buf, |
size_t | len | ||
) |
Gets the current time as a string.
[out] | buf | Buffer to receive the string. |
[in] | len | Length of buffer buf (26 characters should be sufficient). |
Does not throw.
int gmx_gethostname | ( | char * | buf, |
size_t | len | ||
) |
Gets the hostname as given by gethostname(), if available.
[out] | buf | Buffer to receive the hostname. |
[in] | len | Length of buffer buf (must be >= 8). |
If the value is not available, "unknown" is returned. name
should have at least size len
.
Does not throw.
int gmx_getpid | ( | void | ) |
Returns the process ID of the current process.
Does not throw.
int gmx_getuid | ( | void | ) |
Returns the current user ID, or -1 if not available.
Does not throw.
int gmx_getusername | ( | char * | buf, |
size_t | len | ||
) |
Gets the current user name, if available.
[out] | buf | Buffer to receive the username. |
[in] | len | Length of buffer buf (must be >= 8). |
Does not throw.
gmx_bool gmx_omp_check_thread_affinity | ( | char ** | message | ) |
Check for externally set thread affinity to avoid conflicts with GROMACS internal setting.
[out] | message | Receives the message to be shown to the user. |
true
if we can set thread affinity ourselves.While GNU OpenMP does not set affinity by default, the Intel OpenMP library does. This conflicts with the internal affinity (especially thread-MPI) setting, results in incorrectly locked threads, and causes dreadful performance.
The KMP_AFFINITY environment variable is used by Intel, GOMP_CPU_AFFINITY by the GNU compilers (Intel also honors it well). If any of the variables is set, we should honor it and disable the internal pinning. When using Intel OpenMP, we will disable affinity if the user did not set it manually through one of the aforementioned environment variables.
Note that the Intel OpenMP affinity disabling will only take effect if this function is called before the OpenMP library gets initialized, which happens when the first call is made into a compilation unit that contains OpenMP pragmas.
If this function returns false
, the caller is responsible to disable the pinning, show the message from *message
to the user, and free the memory allocated for *message
. If the return value is true
, *message
is NULL.
int gmx_omp_get_max_threads | ( | void | ) |
Returns an integer equal to or greater than the number of threads that would be available if a parallel region without num_threads were defined at that point in the code.
Acts as a wrapper for omp_get_max_threads().
int gmx_omp_get_num_procs | ( | void | ) |
Returns the number of processors available when the function is called.
Acts as a wrapper around omp_get_num_procs().
int gmx_omp_get_thread_num | ( | void | ) |
Returns the thread number of the thread executing within its thread team.
Acts as a wrapper for omp_get_thread_num().
void gmx_omp_set_num_threads | ( | int | num_threads | ) |
Sets the number of threads in subsequent parallel regions, unless overridden by a num_threads clause.
Acts as a wrapper for omp_set_num_threads().
void gmx_qsort | ( | void * | base, |
size_t | nmemb, | ||
size_t | size, | ||
int(*)(const void *, const void *) | compar | ||
) |
Portable threadsafe sort routine.
base | Pointer to first element in list to sort |
nmemb | Number of elements in list |
size | Size in bytes of each element |
compar | Comparison function that takes two pointers to elements being compared as arguments. The function should return an integer less than, equal to, or greater than zero if the first argument is considered to be respectively less than, equal to, or greater than the second. |
int gmx_set_nice | ( | int | level | ) |
Wrapper for nice().
Does not throw.
const char* gmx_version | ( | void | ) |
Version string, containing the version, date, and abbreviated hash.
This can be a plain version if git version info was disabled during the build. The returned string starts with a literal word VERSION
.
const char* gmx_version_git_central_base_hash | ( | void | ) |
Full git hash of the latest commit in a central GROMACS repository.
If git version info was disabled during the build, returns an empty string. Also, if the latest commit was from a central repository, the return value is an empty string.
const char* gmx_version_git_full_hash | ( | void | ) |
Full git hash of the latest commit.
If git version info was disabled during the build, returns an empty string.
void gmx::init | ( | int * | argc, |
char *** | argv | ||
) |
Initializes the GROMACS library.
argc
and argv
are the command line arguments passed to main(). They are allowed to be NULL if GROMACS is not compiled with MPI, MPI_Init() has already been called, or if the MPI library GROMACS is compiled against allows it.
Does not throw.
|
inline |
Tests whether a string is null or empty.
Does not throw.
std::string gmx::joinStrings | ( | InputIterator | begin, |
InputIterator | end, | ||
const char * | separator | ||
) |
Joins strings from a range with a separator in between.
[in] | begin | Iterator the beginning of the range to join. |
[in] | end | Iterator the end of the range to join. |
[in] | separator | String to put in between the joined strings. |
begin
, end
) concatenated with separator
between each pair. std::bad_alloc | if out of memory. |
std::string gmx::joinStrings | ( | const ContainerType & | container, |
const char * | separator | ||
) |
Joins strings from a container with a separator in between.
[in] | container | Strings to join. |
[in] | separator | String to put in between the joined strings. |
container
concatenated with separator
between each pair. std::bad_alloc | if out of memory. |
std::string gmx::joinStrings | ( | const char *const (&) | array[count], |
const char * | separator | ||
) |
Joins strings from an array with a separator in between.
[in] | array | Array of strings to join. |
[in] | separator | String to put in between the joined strings. |
count | Deduced number of elements in array . |
aray
concatenated with separator
between each pair. std::bad_alloc | if out of memory. |
void gmx::printFatalErrorMessage | ( | FILE * | fp, |
const std::exception & | ex | ||
) |
Formats a standard fatal error message for reporting an exception.
[in] | fp | File to format the message to. |
[in] | ex | Exception to format. |
Does not throw. If memory allocation fails or some other error occurs while formatting the error, tries to print a reasonable alternative message.
Normal usage in Gromacs command-line programs is like this:
int gmx::processExceptionAtExit | ( | const std::exception & | ex | ) |
Handles an exception that is causing the program to terminate.
[in] | ex | Exception that is the cause for terminating the program. |
This method should be called as the last thing before terminating the program because of an exception. It exists to terminate the program as gracefully as possible in the case of MPI processing (but the current implementation always calls MPI_Abort()).
See printFatalErrorMessage() for example usage.
Does not throw.
bool gmx::regexMatch | ( | const char * | str, |
const Regex & | regex | ||
) |
Matches a string with a regular expression.
[in] | str | String to match. |
[in] | regex | Regular expression to match. |
regex
matches the whole str
.Does not throw currently, but this is subject to change if/when better error handling is implemented (currently, it returns false if the matching fails, e.g., because of out-of-memory).
std::string gmx::replaceAll | ( | const std::string & | input, |
const char * | from, | ||
const char * | to | ||
) |
Replace all occurrences of a string with another string.
[in] | input | Input string. |
[in] | from | String to find. |
[in] | to | String to use to replace from . |
input
with all occurrences of from
replaced with to
. std::bad_alloc | if out of memory. |
The replacement is greedy and not recursive: starting from the beginning of input
, each match of from
is replaced with to
, and the search for the next match begins after the end of the previous match.
Compexity is O(N), where N is length of output.
std::string gmx::replaceAll | ( | const std::string & | input, |
const std::string & | from, | ||
const std::string & | to | ||
) |
Replace all occurrences of a string with another string.
[in] | input | Input string. |
[in] | from | String to find. |
[in] | to | String to use to replace from . |
input
with all occurrences of from
replaced with to
. std::bad_alloc | if out of memory. |
The replacement is greedy and not recursive: starting from the beginning of input
, each match of from
is replaced with to
, and the search for the next match begins after the end of the previous match.
Compexity is O(N), where N is length of output.
std::string gmx::replaceAllWords | ( | const std::string & | input, |
const char * | from, | ||
const char * | to | ||
) |
Replace whole words with others.
[in] | input | Input string. |
[in] | from | String to find. |
[in] | to | String to use to replace from . |
input
with all from
words replaced with to
. std::bad_alloc | if out of memory. |
Works as replaceAll(), but a match is only considered if it is delimited by non-alphanumeric characters.
std::string gmx::replaceAllWords | ( | const std::string & | input, |
const std::string & | from, | ||
const std::string & | to | ||
) |
Replace whole words with others.
[in] | input | Input string. |
[in] | from | String to find. |
[in] | to | String to use to replace from . |
input
with all from
words replaced with to
. std::bad_alloc | if out of memory. |
Works as replaceAll(), but a match is only considered if it is delimited by non-alphanumeric characters.
ErrorHandlerFunc gmx::setFatalErrorHandler | ( | ErrorHandlerFunc | handler | ) |
Sets callback function for handling errors.
[in] | handler | New error handler function. |
The default error handler prints out the location and reason of the error to stderr, and then calls std::abort().
void gmx::setProgramContext | ( | const ProgramContextInterface * | context | ) |
Sets the global ProgramContextInterface instance.
[in] | context | Program context to set (can be NULL to restore the default context). |
The library does not take ownership of context
. The provided object must remain valid until the global instance is changed by another call to setProgramContext().
This method is not thread-safe. It must be the first call to the library after gmx::init(), and multi-threaded access is only supported after the call completes. If GROMACS is getting called from multiple threads, or uses multiple threads simultaneously, changing the program context is not supported once it is set. If the context is cleared at the end of the program, the caller must ensure that all other threads have been terminated at this point. These constraints simplify the implementation significantly.
Does not throw.
std::vector< std::string > gmx::splitString | ( | const std::string & | str | ) |
Splits a string to whitespace separated tokens.
[in] | str | String to process. |
str
split into tokens at each whitespace sequence. std::bad_alloc | if out of memory. |
This function works like split
in Python, i.e., leading and trailing whitespace is ignored, and consecutive whitespaces are treated as a single separator.
|
inline |
Tests whether a string starts with another string.
[in] | str | String to process. |
[in] | prefix | Prefix to find. |
str
starts with prefix
.Returns true if prefix
is empty. Does not throw.
|
inline |
Tests whether a string starts with another string.
[in] | str | String to process. |
[in] | prefix | Prefix to find. |
str
starts with prefix
.Returns true if prefix
is empty. Does not throw.
std::string gmx::stripString | ( | const std::string & | str | ) |
Removes leading and trailing whitespace from a string.
[in] | str | String to process. |
str
with leading and trailing whitespaces removed. std::bad_alloc | if out of memory. |
std::string gmx::stripSuffixIfPresent | ( | const std::string & | str, |
const char * | suffix | ||
) |
Removes a suffix from a string.
[in] | str | String to process. |
[in] | suffix | Suffix to remove. |
str
with suffix
removed, or str
unmodified if it does not end with suffix
. std::bad_alloc | if out of memory. |
Returns str
if suffix
is NULL or empty.
void gmx::swap | ( | ArrayRef< T > & | a, |
ArrayRef< T > & | b | ||
) |
Simple swap method for ArrayRef objects.
void gmx::swap | ( | ConstArrayRef< T > & | a, |
ConstArrayRef< T > & | b | ||
) |
Simple swap method for ConstArrayRef objects.