api: Deprecations: missing_math.h, parmalist.h, parallel.h, strutil.h, sysutil.h, thread.h, tiffutils.h, ustring.h, type_traits.h (AcademySoftwareFoundation#4338)

* Remove long deprecated and empty header missing_math.h

* paramlist.h: Deprecate the old form of ParamValue constructors.

  People should be using the versions with strongly typed params, not
  raw bools.

* parallel.h: Remove deprecated parallel_for variants.

* strutil.h: Add deprecation warnings to old-style format.

* sysutil.h: Deprecate Sysutil::physical_concurrency.

  Also, I noticed that all the external declarations in this header were
  incorrectly OIIO_API but should have been OIIO_UTIL_API to reflect that
  they are in the OpenImageIO_Util library.

* thread.h: mark deprecated yield() and this_thread_is_in_pool().

* tiffutils.h: removed deprecated redundant functions.

* ustring.h: Remove deprecated ustringHash.

* type_traits.h: Remove deprecated OIIO::void_t, use std::void_t instead.

---------

Signed-off-by: Larry Gritz <lg@larrygritz.com>
Signed-off-by: Scott Wilson <scott@propersquid.com>

Author: lgritz

docs/Deprecations-3.0.md

@@ -67,8 +67,33 @@ long-deprecated API facets. This document lists the deprecations and removals.
   severefmt, messagefmt, debugfmt, respectively, which all use the std::format
   notation.
 
+## missingmath.h
 
-# texture.h
+* This header has been removed entirely. It has was originally needed for
+  pre-C++11 MSVS, but has been unused since OIIO 2.0 (other than transitively
+  including fmath.h).
+
+## parallel.h
+
+* Removed several varieties of `parallel_for` functions where the task
+  functions took a thread ID argument in addition to the range, which have
+  been considered deprecated since OIIO 2.3. Please use task functions that do
+  not take a thread ID parameter.
+
+## paramlist.h
+
+* Removed some ParamValue constructor variants that have been deprecated since
+  OIIO 2.4. The removed variants took an optional `bool` parameter indicating
+  whether the value was copied. If you need to override the usual copy
+  behavior, please use the newer variety of constructors that instead use a
+  "strong" type where you pass `ParamValue:Copy(bool)`.
+
+## strutil.h
+
+* Added deprecation warnings to all the old (printf-convention) string
+  `format()` function.
+
+## texture.h
 
 * Removed stochastic-related tokens from the MipMode and InterpMode enums.
   These were originally experimental but never removed.
@@ -81,7 +106,28 @@ long-deprecated API facets. This document lists the deprecations and removals.
   on batches using the VaryingRef class. These were replaced by alternatives
   a long time ago.
 
-# varyinref.h
+## thread.h
+
+* `OIIO::yield()` now has a deprecation warning, having been marked as
+  deprecatd since OIIO 2.4. Use `std::this_thread::yield()`.
+
+## tiffutils.h
+
+* Removed the version of decode_exif that takes a pointer and length
+  (deprecated since 1.8). Use the version that takes a `string_view`, or the
+  one that takes a `cspan<uint8_t>`.
+
+## type_traits.h
+
+* Removed the `OIIO::void_t` template, which now should be replaced with
+  `std::void_t`.
+
+## ustring.h
+
+* Removed old `ustringHash` (which was just an alias for `std::hash<ustring>`,
+  which should be used instead.
+
+## varyingref.h
 
 * This header has been removed completely, since we no longer use the classes
   it defines.

src/include/OpenImageIO/missing_math.h

@@ -297,75 +297,4 @@ parallel_for_2D(int64_t xbegin, int64_t xend, int64_t ybegin, int64_t yend,
 
 
 
-#if OIIO_VERSION < OIIO_MAKE_VERSION(3, 0, 0)
-
-// Deprecated versions of parallel loops where the task functions take a
-// thread ID in addition to the range. These are deprecated as of OIIO 2.3,
-// will warn about deprecation starting in OIIO 2.4, and will be removed
-// starting with OIIO 3.0.
-
-// OIIO_DEPRECATED("Use tasks that don't take a thread ID (2.3)")
-OIIO_UTIL_API void
-parallel_for_chunked(int64_t begin, int64_t end, int64_t chunksize,
-                     std::function<void(int id, int64_t b, int64_t e)>&& task,
-                     paropt opt = paropt(0, paropt::SplitDir::Y, 1));
-
-// OIIO_DEPRECATED("Use tasks that don't take a thread ID (2.3)")
-OIIO_UTIL_API void
-parallel_for(int64_t begin, int64_t end,
-             std::function<void(int id, int64_t index)>&& task,
-             paropt opt = paropt(0, paropt::SplitDir::Y, 1));
-
-// OIIO_DEPRECATED("Use tasks that don't take a thread ID (2.3)")
-OIIO_UTIL_API void
-parallel_for_chunked_2D(
-    int64_t xbegin, int64_t xend, int64_t xchunksize, int64_t ybegin,
-    int64_t yend, int64_t ychunksize,
-    std::function<void(int id, int64_t, int64_t, int64_t, int64_t)>&& task,
-    paropt opt = 0);
-
-// OIIO_DEPRECATED("Use tasks that don't take a thread ID (2.3)")
-inline void
-parallel_for_2D(int64_t xbegin, int64_t xend, int64_t ybegin, int64_t yend,
-                std::function<void(int id, int64_t i, int64_t j)>&& task,
-                paropt opt = 0)
-{
-    parallel_for_chunked_2D(
-        xbegin, xend, 0, ybegin, yend, 0,
-        [&task](int id, int64_t xb, int64_t xe, int64_t yb, int64_t ye) {
-            for (auto y = yb; y < ye; ++y)
-                for (auto x = xb; x < xe; ++x)
-                    task(id, x, y);
-        },
-        opt);
-}
-
-// Deprecated parallel_for_each. We never used it and I decided I didn't
-// like the implementation and didn't want its guts exposed any more. For
-// compatibility (just in case somebody has used it), implement it serially
-// so that it's correct, even if it's not fast. It will eventually be
-// removed.
-template<class InputIt, class UnaryFunction>
-// OIIO_DEPRECATED("Don't use this (2.3)")
-UnaryFunction
-parallel_for_each(InputIt begin, InputIt end, UnaryFunction f,
-                  paropt opt = paropt(0, paropt::SplitDir::Y, 1))
-{
-    return std::for_each(begin, end, f);
-}
-
-// DEPRECATED(1.8): This version accidentally accepted chunksizes that
-// weren't used. Preserve for a version to not break 3rd party apps.
-OIIO_DEPRECATED("Use the version without chunk sizes (1.8)")
-inline void
-parallel_for_2D(int64_t xbegin, int64_t xend, int64_t /*xchunksize*/,
-                int64_t ybegin, int64_t yend, int64_t /*ychunksize*/,
-                std::function<void(int id, int64_t i, int64_t j)>&& task)
-{
-    parallel_for_2D(xbegin, xend, ybegin, yend, std::move(task));
-}
-
-#endif /* Deprecated functions */
-
-
 OIIO_NAMESPACE_END

src/include/OpenImageIO/parallel.h

@@ -90,31 +90,6 @@ class OIIO_UTIL_API ParamValue {
 
     ParamValue() noexcept { m_data.ptr = nullptr; }
 
-#if OIIO_VERSION_LESS(3, 0, 0) && !defined(OIIO_DOXYGEN)
-    // DEPRECATED(2.4): Use the ones with strongly typed bool parameters
-    ParamValue(const ustring& _name, TypeDesc _type, int _nvalues,
-               const void* _value, bool _copy) noexcept
-    {
-        init_noclear(_name, _type, _nvalues, _value, Copy(_copy));
-    }
-    ParamValue(const ustring& _name, TypeDesc _type, int _nvalues,
-               Interp _interp, const void* _value, bool _copy) noexcept
-    {
-        init_noclear(_name, _type, _nvalues, _interp, _value, Copy(_copy));
-    }
-    ParamValue(string_view _name, TypeDesc _type, int _nvalues,
-               const void* _value, bool _copy) noexcept
-    {
-        init_noclear(ustring(_name), _type, _nvalues, _value, Copy(_copy));
-    }
-    ParamValue(string_view _name, TypeDesc _type, int _nvalues, Interp _interp,
-               const void* _value, bool _copy) noexcept
-    {
-        init_noclear(ustring(_name), _type, _nvalues, _interp, _value,
-                     Copy(_copy));
-    }
-#endif
-
     ParamValue(const ustring& _name, TypeDesc _type, int _nvalues,
                const void* _value, Copy _copy = Copy(true)) noexcept
     {
@@ -187,31 +162,6 @@ class OIIO_UTIL_API ParamValue {
 
     ~ParamValue() noexcept { clear_value(); }
 
-#if OIIO_VERSION_LESS(3, 0, 0) && !defined(OIIO_DOXYGEN)
-    // DEPRECATED(2.4): Use the ones with strongly typed bool parameters
-    void init(ustring _name, TypeDesc _type, int _nvalues, Interp _interp,
-              const void* _value, bool _copy) noexcept
-    {
-        clear_value();
-        init_noclear(_name, _type, _nvalues, _interp, _value, Copy(_copy));
-    }
-    void init(ustring _name, TypeDesc _type, int _nvalues, const void* _value,
-              bool _copy) noexcept
-    {
-        init(_name, _type, _nvalues, INTERP_CONSTANT, _value, Copy(_copy));
-    }
-    void init(string_view _name, TypeDesc _type, int _nvalues,
-              const void* _value, bool _copy) noexcept
-    {
-        init(ustring(_name), _type, _nvalues, _value, Copy(_copy));
-    }
-    void init(string_view _name, TypeDesc _type, int _nvalues, Interp _interp,
-              const void* _value, bool _copy) noexcept
-    {
-        init(ustring(_name), _type, _nvalues, _interp, _value, Copy(_copy));
-    }
-#endif
-
     void init(ustring _name, TypeDesc _type, int _nvalues, Interp _interp,
               const void* _value, Copy _copy) noexcept
     {

src/include/OpenImageIO/paramlist.h

@@ -41,14 +41,7 @@
 #    define OIIO_FORMAT_IS_FMT 0
 #endif
 
-// If OIIO_HIDE_FORMAT is defined, mark the old-style format functions as
-// deprecated. (This is a debugging aid for downstream projects who want to
-// root out any places where they might be using the old one).
-#ifdef OIIO_HIDE_FORMAT
-#    define OIIO_FORMAT_DEPRECATED OIIO_DEPRECATED("old style (printf-like) formatting version of this function is deprecated")
-#else
-#    define OIIO_FORMAT_DEPRECATED
-#endif
+#define OIIO_FORMAT_DEPRECATED OIIO_DEPRECATED("old style (printf-like) formatting version of this function is deprecated")
 
 // If OIIO_PRINT_IS_SYNCHRONIZED is not defined, assume unsynchronized.
 #ifndef OIIO_PRINT_IS_SYNCHRONIZED

src/include/OpenImageIO/strutil.h

@@ -44,52 +44,48 @@ namespace Sysutil {
 /// (which can be misleading because gcc allocates quite a bit of
 /// virtual, but not actually resident until malloced, memory per
 /// thread).
-OIIO_API size_t
+OIIO_UTIL_API size_t
 memory_used(bool resident = true);
 
 /// The amount of physical RAM on this machine, in bytes.
 /// If it can't figure it out, it will return 0.
-OIIO_API size_t
+OIIO_UTIL_API size_t
 physical_memory();
 
 /// Convert calendar time pointed by 'time' into local time and save it in
 /// 'converted_time' variable. This is a fully reentrant/thread-safe
 /// alternative to the non-reentrant C localtime() call.
-OIIO_API void
+OIIO_UTIL_API void
 get_local_time(const time_t* time, struct tm* converted_time);
 
 /// Return the full path of the currently-running executable program.
 ///
-OIIO_API std::string
+OIIO_UTIL_API std::string
 this_program_path();
 
 /// Return the value of an environment variable, or if it is not found in
 /// the environment, return `defaultval`, which in turn defaults to the
 /// empty string.
-OIIO_API string_view
-getenv(string_view name, string_view defaultval);
-
-// Legacy for link compatibility. DEPRECATED(2.3)
-OIIO_API string_view
-getenv(string_view name);
+OIIO_UTIL_API string_view
+getenv(string_view name, string_view defaultval = {});
 
 /// Sleep for the given number of microseconds.
 ///
-OIIO_API void
+OIIO_UTIL_API void
 usleep(unsigned long useconds);
 
 /// Try to put the process into the background so it doesn't continue to
 /// tie up any shell that it was launched from.  The arguments are the
 /// argc/argv that describe the program and its command line arguments.
 /// Return true if successful, false if it was unable to do so.
-OIIO_API bool
+OIIO_UTIL_API bool
 put_in_background(int argc, char* argv[]);
 
 /// Number of virtual cores available on this platform (including
 /// hyperthreads). Note that this is just a wrapper/synonym for C++
 /// std::thread::hardware_concurrency(), and was put in OIIO to allow its use
 /// before C++11 was our minimum.
-OIIO_API unsigned int
+OIIO_UTIL_API unsigned int
 hardware_concurrency();
 
 #if OIIO_DISABLE_DEPRECATED < OIIO_MAKE_VERSION(2, 6, 0)
@@ -101,18 +97,21 @@ hardware_concurrency();
 /// release of OpenImageIO. It is now a synonym for hardware_concurrency().
 OIIO_DEPRECATED(
     "unreliable, replace with hardware_concurrency() [DEPRECATED in 2.6.0.0]")
-OIIO_API unsigned int
-physical_concurrency();
+inline unsigned int
+physical_concurrency()
+{
+    return hardware_concurrency();
+}
 #endif
 
 /// Get the maximum number of open file handles allowed on this system.
-OIIO_API size_t
+OIIO_UTIL_API size_t
 max_open_files();
 
 /// Return a string containing a readable stack trace from the point where
 /// it was called. Return an empty string if not supported on this platform
 /// or this build of OpenImageIO.
-OIIO_API std::string
+OIIO_UTIL_API std::string
 stacktrace();
 
 /// Turn on automatic stacktrace dump to the named file if the program
@@ -121,23 +120,23 @@ stacktrace();
 /// be "stdout" or "stderr" to merely print the trace to stdout or stderr,
 /// respectively. If the name is "", it will disable the auto-stacktrace
 /// printing.
-OIIO_API bool
+OIIO_UTIL_API bool
 setup_crash_stacktrace(string_view filename);
 
 /// Try to figure out how many columns wide the terminal window is. May not
 /// be correct on all systems, will default to 80 if it can't figure it out.
-OIIO_API int
+OIIO_UTIL_API int
 terminal_columns();
 
 /// Try to figure out how many rows tall the terminal window is. May not be
 /// correct on all systems, will default to 24 if it can't figure it out.
-OIIO_API int
+OIIO_UTIL_API int
 terminal_rows();
 
 
 /// Term object encapsulates information about terminal output for the sake
 /// of constructing ANSI escape sequences.
-class OIIO_API Term {
+class OIIO_UTIL_API Term {
 public:
     /// Default ctr: assume ANSI escape sequences are ok.
     Term() noexcept {}

src/include/OpenImageIO/sysutil.h

@@ -90,6 +90,7 @@ typedef std::lock_guard<std::recursive_timed_mutex> recursive_timed_lock_guard;
 
 /// Yield the processor for the rest of the timeslice.
 /// DEPRECATED(2.4): Use std::this_thread::yield() instead.
+OIIO_DEPRECATED("Use std::this_thread::yield() [2.4]")
 inline void
 yield() noexcept
 {
@@ -725,6 +726,7 @@ class OIIO_UTIL_API thread_pool {
     /// can be used to limit a pool thread from unadvisedly adding its own
     /// subtasks to clog up the pool.
     /// DEPRECATED(2.1) -- use is_worker() instead.
+    OIIO_DEPRECATED("use is_worker [2.1]")
     bool this_thread_is_in_pool() const;
 
     /// Register a thread (not already in the thread pool itself) as working
@@ -737,8 +739,6 @@ class OIIO_UTIL_API thread_pool {
     /// the pool?
     bool is_worker(std::thread::id id) const;
     bool is_worker() const { return is_worker(std::this_thread::get_id()); }
-    // Non-const versions: DEPRECATED(2.1)
-    bool is_worker(std::thread::id id);
 
     /// How many jobs are waiting to run?  (Use with caution! Can be out of
     /// date by the time you look at it.)