From fcd3d91281891bda5d5f4fe60ebb2d282de439c6 Mon Sep 17 00:00:00 2001 From: Aina Niemetz Date: Sun, 11 Aug 2019 14:08:30 -0700 Subject: [PATCH] New C++ API: Add documentation/guidelines for API guards. (#3178) --- src/api/cvc4cpp.cpp | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/src/api/cvc4cpp.cpp b/src/api/cvc4cpp.cpp index 942235e9c..1538d3558 100644 --- a/src/api/cvc4cpp.cpp +++ b/src/api/cvc4cpp.cpp @@ -12,6 +12,23 @@ ** \brief The CVC4 C++ API. ** ** The CVC4 C++ API. + ** + ** A brief note on how to guard API functions: + ** + ** In general, we think of API guards as a fence -- they are supposed to make + ** sure that no invalid arguments get passed into internal realms of CVC4. + ** Thus we always want to catch such cases on the API level (and can then + ** assert internally that no invalid argument is passed in). + ** + ** The only special case is when we use 3rd party back-ends we have no control + ** over, and which throw (invalid_argument) exceptions anyways. In this case, + ** we do not replicate argument checks but delegate them to the back-end, + ** catch thrown exceptions, and raise a CVC4ApiException. + ** + ** Our Integer implementation, e.g., is such a special case since we support + ** two different back end implementations (GMP, CLN). Be aware that they do + ** not fully agree on what is (in)valid input, which requires extra checks for + ** consistent behavior (see Solver::mkRealFromStrHelper for an example). **/ #include "api/cvc4cpp.h" -- 2.30.2