From 1d2586214652cadde6cd11acaddf84076b799afa Mon Sep 17 00:00:00 2001 From: Axel Kohlmeyer Date: Sun, 26 Nov 2023 13:11:18 -0500 Subject: [PATCH] update documentation for the fact that exceptions in LAMMPS are always used --- doc/src/Developer_unittest.rst | 18 +++++------------- doc/src/Fortran.rst | 15 --------------- doc/src/Library.rst | 16 +++++++++------- doc/src/Python_error.rst | 4 +--- doc/src/Python_install.rst | 3 +-- doc/src/variable.rst | 7 +++---- src/library.cpp | 15 +-------------- 7 files changed, 20 insertions(+), 58 deletions(-) diff --git a/doc/src/Developer_unittest.rst b/doc/src/Developer_unittest.rst index 9886e9e4b4..67c5ce365a 100644 --- a/doc/src/Developer_unittest.rst +++ b/doc/src/Developer_unittest.rst @@ -180,19 +180,11 @@ discarded but by setting the verbose flag (via setting the ``TEST_ARGS`` environment variable, ``TEST_ARGS=-v``) it can be printed and used to understand why tests fail unexpectedly. -Another complexity of these tests stems from the need to capture -situations where LAMMPS will stop with an error, i.e. handle so-called -"death tests". Here the LAMMPS code will operate differently depending -on whether it was configured to throw C++ exceptions on errors or call -either ``exit()`` or ``MPI_Abort()``. In the latter case, the test code -also needs to detect whether LAMMPS was compiled with the OpenMPI -library, as OpenMPI is **only** compatible the death test options of the -GoogleTest library when C++ exceptions are enabled; otherwise those -"death tests" must be skipped to avoid reporting bogus failures. The -specifics of this step are implemented in the ``TEST_FAILURE()`` -macro. These tests operate by capturing the screen output when executing -the failing command and then comparing that with a provided regular -expression string pattern. Example: +The specifics of so-called "death tests", i.e. conditions where LAMMPS +should fail and throw an exception, are implemented in the +``TEST_FAILURE()`` macro. These tests operate by capturing the screen +output when executing the failing command and then comparing that with a +provided regular expression string pattern. Example: .. code-block:: c++ diff --git a/doc/src/Fortran.rst b/doc/src/Fortran.rst index 913c31842e..76fdff753a 100644 --- a/doc/src/Fortran.rst +++ b/doc/src/Fortran.rst @@ -3038,14 +3038,6 @@ Procedures Bound to the :f:type:`lammps` Derived Type This function can be used to query if an error inside of LAMMPS has thrown a :ref:`C++ exception `. - .. note:: - - This function will always report "no error" when the LAMMPS library - has been compiled without ``-DLAMMPS_EXCEPTIONS``, which turns fatal - errors aborting LAMMPS into C++ exceptions. You can use the library - function :cpp:func:`lammps_config_has_exceptions` to check if this is - the case. - :to: :cpp:func:`lammps_has_error` :r has_error: ``.TRUE.`` if there is an error. :rtype has_error: logical @@ -3068,13 +3060,6 @@ Procedures Bound to the :f:type:`lammps` Derived Type would happen only in a single MPI rank and thus may not be recoverable, as other MPI ranks may be waiting on the failing MPI rank(s) to send messages. - .. note:: - - This function will do nothing when the LAMMPS library has been - compiled without ``-DLAMMPS_EXCEPTIONS``, which turns errors aborting - LAMMPS into C++ exceptions. You can use the function - :f:func:`config_has_exceptions` to check whether this is the case. - :p character(len=\*) buffer: string buffer to copy the error message into :o integer(c_int) status [optional]: 1 when all ranks had the error, 2 on a single-rank error. diff --git a/doc/src/Library.rst b/doc/src/Library.rst index 09561cda82..50c28b7fcd 100644 --- a/doc/src/Library.rst +++ b/doc/src/Library.rst @@ -80,13 +80,15 @@ run LAMMPS in serial mode. :class: note If the LAMMPS executable encounters an error condition, it will abort - after printing an error message. For a library interface this is - usually not desirable. Thus LAMMPS can be compiled to to :ref:`throw - a C++ exception ` instead. If enabled, the library - functions will catch those exceptions and return. The error status - :cpp:func:`can be queried ` and an :cpp:func:`error - message retrieved `. We thus - recommend enabling C++ exceptions when using the library interface, + after printing an error message. It does so by catching the + exceptions that LAMMPS could throw. For a C library interface this + is usually not desirable since the calling code might lack the + ability to catch such exceptions. Thus, the library functions will + catch those exceptions and return from the affected functions. The + error status :cpp:func:`can be queried ` and an + :cpp:func:`error message retrieved `. + This is, for example used by the :doc:`LAMMPS python module + ` and then a suitable Python exception is thrown. .. admonition:: Using the C library interface as a plugin :class: note diff --git a/doc/src/Python_error.rst b/doc/src/Python_error.rst index f6a94c0e82..6aec8df391 100644 --- a/doc/src/Python_error.rst +++ b/doc/src/Python_error.rst @@ -15,9 +15,7 @@ Python exception handling mechanism. try: # LAMMPS will normally terminate itself and the running process if an error - # occurs. This would kill the Python interpreter. To avoid this, make sure to - # compile with LAMMPS_EXCEPTIONS enabled. This ensures the library API calls - # will not terminate the parent process. Instead, the library wrapper will + # occurs. This would kill the Python interpreter. The library wrapper will # detect that an error has occured and throw a Python exception lmp.command('unknown') diff --git a/doc/src/Python_install.rst b/doc/src/Python_install.rst index c4fbec0be4..01610b84f0 100644 --- a/doc/src/Python_install.rst +++ b/doc/src/Python_install.rst @@ -5,8 +5,7 @@ The LAMMPS Python module enables calling the :ref:`LAMMPS C library API ` from Python by dynamically loading functions in the LAMMPS shared library through the Python `ctypes `_ module. Because of the dynamic loading, it is required that LAMMPS is -compiled in :ref:`"shared" mode `. It is also recommended to -compile LAMMPS with :ref:`C++ exceptions ` enabled. +compiled in :ref:`"shared" mode `. Two components are necessary for Python to be able to invoke LAMMPS code: diff --git a/doc/src/variable.rst b/doc/src/variable.rst index cf136c7d89..a70ac25836 100644 --- a/doc/src/variable.rst +++ b/doc/src/variable.rst @@ -1044,10 +1044,9 @@ to built-in commands. For all of these styles except *command*, appending of active suffixes is also tried before reporting failure. The *feature* category checks the availability of the following -compile-time enabled features: GZIP support, PNG support, JPEG -support, FFMPEG support, and C++ exceptions for error -handling. Corresponding names are *gzip*, *png*, *jpeg*, *ffmpeg* and -*exceptions*\ . +compile-time enabled features: GZIP support, PNG support, JPEG support, +FFMPEG support, and C++ exceptions for error handling. Corresponding +names are *gzip*, *png*, *jpeg*, *ffmpeg* and *exceptions*\ . Example: Only dump in a given format if the compiled binary supports it. diff --git a/src/library.cpp b/src/library.cpp index 363110e5f5..1acdfc4787 100644 --- a/src/library.cpp +++ b/src/library.cpp @@ -481,7 +481,7 @@ void lammps_error(void *handle, int error_type, const char *error_text) } END_CAPTURE - // with enabled exceptions the above code will simply throw an + // in case of an error the above code will simply throw an // exception and record the error message. So we have to explicitly // stop here like we do in main.cpp if (lammps_has_error(handle)) { @@ -6608,13 +6608,6 @@ has thrown a :ref:`C++ exception `. instance, but instead would check the global error buffer of the library interface. -.. note:: - - This function will always report "no error" when the LAMMPS library - has been compiled without ``-DLAMMPS_EXCEPTIONS``, which turns fatal - errors aborting LAMMPS into C++ exceptions. You can use the library - function :cpp:func:`lammps_config_has_exceptions` to check whether this is - the case. \endverbatim * * \param handle pointer to a previously created LAMMPS instance cast to ``void *`` or NULL @@ -6663,12 +6656,6 @@ the failing MPI ranks to send messages. The *buffer* pointer may be ``NULL``. This will clear any error status without copying the error message. -.. note:: - - This function will do nothing when the LAMMPS library has been - compiled without ``-DLAMMPS_EXCEPTIONS``, which turns errors aborting - LAMMPS into C++ exceptions. You can use the library function - :cpp:func:`lammps_config_has_exceptions` to check whether this is the case. \endverbatim * * \param handle pointer to a previously created LAMMPS instance cast to ``void *`` or NULL.