include/k4FWCore/GaudiChecks.h

0001 /*
0002  * Copyright (c) 2014-2024 Key4hep-Project.
0003  *
0004  * This file is part of Key4hep.
0005  * See https://key4hep.github.io/key4hep-doc/ for further info.
0006  *
0007  * Licensed under the Apache License, Version 2.0 (the "License");
0008  * you may not use this file except in compliance with the License.
0009  * You may obtain a copy of the License at
0010  *
0011  *     http://www.apache.org/licenses/LICENSE-2.0
0012  *
0013  * Unless required by applicable law or agreed to in writing, software
0014  * distributed under the License is distributed on an "AS IS" BASIS,
0015  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
0016  * See the License for the specific language governing permissions and
0017  * limitations under the License.
0018  */
0019 /**
0020  * @file k4FWCore/k4FWCore/include/k4FWCore/check.h
0021  * @author scott snyder <snyder@bnl.gov>
0022  * @date Apr, 2025
0023  * @brief Helper to check return codes in a Gaudi component.
0024  */
0025
0026 #ifndef K4FWCORE_K4_CHECK_H
0027 #define K4FWCORE_K4_CHECK_H
0028
0029 #include "GaudiKernel/StatusCode.h"
0030
0031 /**
0032  * @brief Helper to check return codes in a Gaudi component.
0033  *
0034  * <code>K4_GAUDI_CHECK( EXP )</code> will evaluate @c EXP.  If this results
0035  * in something that evaluates to @c false (including @c StatusCode::FAILURE),
0036  * we emit an error message and immediately return a @c StatusCode::FAILURE.
0037  * This can be used to make checking the results of calls from Gaudi components
0038  * easier to read.  For example, a typical call to something that returns
0039  * a @c StatusCode might be implemented something like this:
0040  *
0041  *@code
0042  *  StatusCode sc = something();
0043  *  if (! sc.isSuccess() ) {
0044  *    error() << "Something went wrong." << endmsg;
0045  *    return sc;
0046  *  }
0047  @endcode
0048  *
0049  * This has several undesirable properties.  First, it is overly verbose.
0050  * 80% of the code in this example is devoted to error handling; if there
0051  * are many of these, it becomes difficult to read what the code is
0052  * actually doing.
0053  *
0054  * Second, there is no standardization of the error messages produced,
0055  * and they are sometimes difficult to trace back to the actual offending
0056  * source code.
0057  *
0058  * Third, code like this typically gets written by cut-and-paste,
0059  * which is notoriously error-prone.
0060  *
0061  * The helper here can address these issues; rather than the code above, use
0062  *
0063  *@code
0064  *  K4_GAUDI_CHECK( something() );
0065  @endcode
0066  *
0067  * The error message produced by this will contain the text of the
0068  * expression that failed, as well as the corresponding source file and line.
0069  * Note that macro has to be used in a context such as a Gaudi component
0070  * where the @c error() function is defined to return a Gaudi @c MsgStream.
0071  */
0072 #define K4_GAUDI_CHECK(EXP)                                                                                            \
0073   do {                                                                                                                 \
0074     if (!(EXP)) {                                                                                                      \
0075       error() << __FILE__ << ":" << __LINE__ << " error returned from: " << #EXP << endmsg;                            \
0076       return StatusCode::FAILURE;                                                                                      \
0077     }                                                                                                                  \
0078   } while (0)
0079
0080 #endif // not K4FWCORE_K4_CHECK_H