api: Introduce new scheme for preserving ABI compatibility

This patch partially implements the new scheme for preserving ABI
compatibility across minor (yearly) releases.

"Major" or "first digit" releases, which only happen once every
several years for us, are full ABI+API breaks. Previously, "minor" or
"second digit" releases, which are annual, have fully incompatible
ABIs, with separate namespaces to enforce it. Here, we are striving to
allow our annual/minor releases to no longer break ABI, to make upgrading
easier for downstream users.

The basics are that once a symbol is introduced, it will forever live
in the namespace of that release. Subsequent release years will have
their own namespaces, but will either alias or duplicate the symbols.
This is enabled by our recent (in the lead-up to 3.1) introduction of
a split 2-part namespacing scheme. So 3.2 is the first release that
has the potential to perserve compatibility with 3.1 in this way.

In this PR, I do so just for libOpenImageIO_Util, as a proof of
concept.  It works! -- as measured by being able to have our automated
ABI checker show 100% back compatibility with 3.1 for the utility
library. But let's look this over and decide if we like it (it does
involve some hoop jumping and extra care as we develop), and if we do,
then in a second (or more) PR, I will bring this sauce to the rest of
the main libOpenImageIO library.

Signed-off-by: Larry Gritz <[email protected]>

Author: lgritz

.github/workflows/ci.yml

@@ -388,7 +388,7 @@ jobs:
             simd: "avx2,f16c"
             skip_tests: 1
             # abi_check: v3.1.3.0
-            abi_check: ae5dca7865c9956b43cc04dee00a65ad893e251e
+            abi_check: 9bfcce725a3806a3f70c7e838d9d98d6d95c917a
             setenvs: export OIIO_CMAKE_FLAGS="-DOIIO_BUILD_TOOLS=0 -DOIIO_BUILD_TESTS=0 -DUSE_PYTHON=0"
                             USE_OPENCV=0 USE_FFMPEG=0 USE_PYTHON=0 USE_FREETYPE=0
 

src/include/OpenImageIO/argparse.h

@@ -20,9 +20,13 @@
 #include <OpenImageIO/paramlist.h>
 #include <OpenImageIO/strutil.h>
 
+// Define symbols that let client applications determine if newly added
+// features are supported.
+#define OIIO_ARGPARSE_SUPPORTS_BRIEFUSAGE 1
+#define OIIO_ARGPARSE_SUPPORTS_HUMAN_PARAMNAME 1
 
-OIIO_NAMESPACE_BEGIN
 
+OIIO_NAMESPACE_3_1_BEGIN
 
 /////////////////////////////////////////////////////////////////////////////
 ///
@@ -173,7 +177,7 @@ OIIO_NAMESPACE_BEGIN
 
 class OIIO_UTIL_API ArgParse {
 public:
-    class Arg;  // Forward declarion of Arg
+    class Arg;  // Forward declaration of Arg
 
     // ------------------------------------------------------------------
     /// @defgroup Setting up an ArgParse
@@ -782,11 +786,4 @@ class OIIO_UTIL_API ArgParse {
     void usage() const { print_help(); }
 };
 
-
-
-// Define symbols that let client applications determine if newly added
-// features are supported.
-#define OIIO_ARGPARSE_SUPPORTS_BRIEFUSAGE 1
-#define OIIO_ARGPARSE_SUPPORTS_HUMAN_PARAMNAME 1
-
-OIIO_NAMESPACE_END
+OIIO_NAMESPACE_3_1_END

src/include/OpenImageIO/benchmark.h

@@ -24,7 +24,7 @@
 #endif
 
 
-OIIO_NAMESPACE_BEGIN
+OIIO_NAMESPACE_3_1_BEGIN
 
 /// DoNotOptimize(val) is a helper function for timing benchmarks that fools
 /// the compiler into thinking the the location 'val' is used and will not
@@ -310,6 +310,7 @@ class OIIO_UTIL_API Benchmarker {
 
 
 
+
 /// Helper template that runs a function (or functor) n times, using a
 /// Timer to benchmark the results, and returning the fastest trial.  If
 /// 'range' is non-NULL, the range (max-min) of the various time trials
@@ -470,6 +471,24 @@ OIIO_FORCEINLINE void clobber_all_memory() { }
 
 #endif
 
+OIIO_UTIL_API std::ostream& operator<<(std::ostream& out,
+                                       const Benchmarker& bench);
 
+OIIO_NAMESPACE_3_1_END
 
+
+// Compatibility
+OIIO_NAMESPACE_BEGIN
+#ifndef OIIO_DOXYGEN
+using v3_1::Benchmarker;
+using v3_1::clobber;
+using v3_1::clobber_all_memory;
+using v3_1::DoNotOptimize;
+using v3_1::time_trial;
+using v3_1::timed_thread_wedge;
+using v3_1::operator<<;
+namespace pvt {
+using v3_1::pvt::use_char_ptr;
+}
+#endif
 OIIO_NAMESPACE_END

src/include/OpenImageIO/color.h

@@ -12,6 +12,9 @@
 #include <OpenImageIO/typedesc.h>
 #include <OpenImageIO/ustring.h>
 
+// Preprocessor symbol to allow conditional compilation depending on
+// whether the ColorProcessor class is exposed (it was not prior to OIIO 1.9).
+#define OIIO_HAS_COLORPROCESSOR 1
 
 //
 // Some general color management information materials to have handy:
@@ -23,7 +26,12 @@
 //
 
 
-OIIO_NAMESPACE_BEGIN
+// Preprocessor symbol to allow conditional compilation depending on
+// whether the ColorConfig returns ColorProcessor shared pointers or raw.
+#define OIIO_COLORCONFIG_USES_SHARED_PTR 1
+
+
+OIIO_NAMESPACE_3_1_BEGIN
 
 /// The ColorProcessor encapsulates a baked color transformation, suitable for
 /// application to raw pixels, or ImageBuf(s). These are generated using
@@ -50,17 +58,9 @@ class OIIO_API ColorProcessor {
     }
 };
 
-// Preprocessor symbol to allow conditional compilation depending on
-// whether the ColorProcessor class is exposed (it was not prior to OIIO 1.9).
-#define OIIO_HAS_COLORPROCESSOR 1
-
-
 
-typedef std::shared_ptr<ColorProcessor> ColorProcessorHandle;
 
-// Preprocessor symbol to allow conditional compilation depending on
-// whether the ColorConfig returns ColorProcessor shared pointers or raw.
-#define OIIO_COLORCONFIG_USES_SHARED_PTR 1
+using ColorProcessorHandle = std::shared_ptr<ColorProcessor>;
 
 
 
@@ -445,7 +445,18 @@ class OIIO_API ColorConfig {
     Impl* getImpl() const { return m_impl.get(); }
 };
 
+OIIO_NAMESPACE_3_1_END
+
 
+// Compatibility
+#ifndef OIIO_DOXYGEN
+OIIO_NAMESPACE_BEGIN
+using v3_1::ColorProcessorHandle;
+OIIO_NAMESPACE_END
+#endif
+
+
+OIIO_NAMESPACE_BEGIN
 
 /// Utility -- convert sRGB value to linear transfer function, without
 /// any change in color primaries.

src/include/OpenImageIO/deepdata.h

@@ -12,8 +12,6 @@
 
 OIIO_NAMESPACE_BEGIN
 
-
-struct TypeDesc;
 class ImageSpec;
 
 

src/include/OpenImageIO/errorhandler.h

@@ -10,7 +10,7 @@
 #include <OpenImageIO/strutil.h>
 
 
-OIIO_NAMESPACE_BEGIN
+OIIO_NAMESPACE_3_1_BEGIN
 
 /// ErrorHandler is a simple class that accepts error messages
 /// (classified as errors, severe errors, warnings, info, messages, or
@@ -136,4 +136,4 @@ class OIIO_UTIL_API ErrorHandler {
     int m_verbosity;
 };
 
-OIIO_NAMESPACE_END
+OIIO_NAMESPACE_3_1_END

src/include/OpenImageIO/filesystem.h

@@ -44,19 +44,29 @@
 
 
 
-OIIO_NAMESPACE_BEGIN
-
+OIIO_NAMESPACE_3_1_BEGIN
 #if OIIO_FILESYSTEM_USE_STDIO_FILEBUF
 // MingW uses GCC to build, but does not support having a wchar_t* passed as argument
 // of ifstream::open or ofstream::open. To properly support UTF-8 encoding on MingW we must
 // use the __gnu_cxx::stdio_filebuf GNU extension that can be used with _wfsopen and returned
 // into a istream which share the same API as ifsteam. The same reasoning holds for ofstream.
-typedef basic_ifstream<char> ifstream;
-typedef basic_ofstream<char> ofstream;
+using ifstream = basic_ifstream<char>;
+using ofstream = basic_ofstream<char>;
 #else
-typedef std::ifstream ifstream;
-typedef std::ofstream ofstream;
+using ifstream = std::ifstream;
+using ofstream = std::ofstream;
 #endif
+OIIO_NAMESPACE_3_1_END
+
+// Compatibility
+OIIO_NAMESPACE_BEGIN
+using ifstream = v3_1::ifstream;
+using ofstream = v3_1::ofstream;
+OIIO_NAMESPACE_END
+
+
+
+OIIO_NAMESPACE_3_1_BEGIN
 
 /// @namespace Filesystem
 ///
@@ -243,12 +253,12 @@ OIIO_UTIL_API std::string current_path ();
 
 /// Version of std::ifstream.open that can handle UTF-8 paths
 ///
-OIIO_UTIL_API void open (OIIO::ifstream &stream, string_view path,
+OIIO_UTIL_API void open (ifstream &stream, string_view path,
                     std::ios_base::openmode mode = std::ios_base::in);
 
 /// Version of std::ofstream.open that can handle UTF-8 paths
 ///
-OIIO_UTIL_API void open (OIIO::ofstream &stream, string_view path,
+OIIO_UTIL_API void open (ofstream &stream, string_view path,
                     std::ios_base::openmode mode = std::ios_base::out);
 
 /// Version of C open() that can handle UTF-8 paths, returning an integer
@@ -584,4 +594,13 @@ class OIIO_UTIL_API IOMemReader : public IOProxy {
 
 };  // namespace Filesystem
 
+OIIO_NAMESPACE_3_1_END
+
+// Compatibility
+#ifndef OIIO_DOXYGEN
+OIIO_NAMESPACE_BEGIN
+namespace Filesystem {
+using namespace OIIO::v3_1::Filesystem;
+};  // namespace Filesystem
 OIIO_NAMESPACE_END
+#endif

src/include/OpenImageIO/filter.h

@@ -12,7 +12,7 @@
 #include <OpenImageIO/string_view.h>
 
 
-OIIO_NAMESPACE_BEGIN
+OIIO_NAMESPACE_3_1_BEGIN
 
 /// Quick structure that describes a filter.
 ///
@@ -156,4 +156,4 @@ class OIIO_UTIL_API Filter2D {
 };
 
 
-OIIO_NAMESPACE_END
+OIIO_NAMESPACE_3_1_END

src/include/OpenImageIO/function_view.h

@@ -47,7 +47,7 @@
 #include <OpenImageIO/platform.h>
 
 
-OIIO_NAMESPACE_BEGIN
+OIIO_NAMESPACE_3_1_BEGIN
 
 
 /// function_view<R(T...)> is a lightweight non-owning generic callable
@@ -105,4 +105,10 @@ template<typename Ret, typename... Params> class function_view<Ret(Params...)> {
 };
 
 
+OIIO_NAMESPACE_3_1_END
+
+
+// Compatibility
+OIIO_NAMESPACE_BEGIN
+using v3_1::function_view;
 OIIO_NAMESPACE_END

src/include/OpenImageIO/hash.h

@@ -27,7 +27,7 @@
 #include <OpenImageIO/span.h>
 
 
-OIIO_NAMESPACE_BEGIN
+OIIO_NAMESPACE_3_1_BEGIN
 
 using std::hash;
 using std::unordered_map;
@@ -563,7 +563,7 @@ inline uint128_t Fingerprint128(const Str& s) {
 class CSHA1;  // opaque forward declaration
 
 
-/// Class that encapsulates SHA-1 hashing, a crypticographic-strength
+/// Class that encapsulates SHA-1 hashing, a cryptographic-strength
 /// 160-bit hash function.  It's not as fast as our other hashing
 /// methods, but has an extremely low chance of having collisions.
 class OIIO_API SHA1 {
@@ -616,4 +616,16 @@ class OIIO_API SHA1 {
 };
 
 
+OIIO_NAMESPACE_3_1_END
+
+
+// Compatibility
+OIIO_NAMESPACE_BEGIN
+// Replicate the hashing namespaces in v3_1:: inside OIIO::
+namespace fasthash { using namespace OIIO::v3_1::fasthash; }
+namespace xxhash { using namespace OIIO::v3_1::xxhash; }
+namespace bjhash { using namespace OIIO::v3_1::bjhash; }
+namespace murmur { using namespace OIIO::v3_1::murmur; }
+namespace farmhash { using namespace OIIO::v3_1::farmhash; }
+using v3_1::SHA1;
 OIIO_NAMESPACE_END