Disable PointerHolder by default

Jay Berkenbilt · m-holger
1 parent 20126227
Showing 14 changed files with 30 additions and 27 deletions
CMakeLists.txt
ChangeLog
include/qpdf/Buffer.hh
include/qpdf/ClosedFileInputSource.hh
include/qpdf/InputSource.hh
include/qpdf/JSON.hh
include/qpdf/Pipeline.hh
include/qpdf/Pl_Buffer.hh
include/qpdf/Pl_QPDFTokenizer.hh
include/qpdf/PointerHolder.hh
job.sums
manual/design.rst
manual/release-notes.rst
pkg-test/qpdf-version.cc
@@ -120,7 +120,6 @@ if(NOT (BUILD_STATIC_LIBS OR BUILD_SHARED_LIBS))
 endif()
 set(CMAKE_INCLUDE_DIRECTORIES_PROJECT_BEFORE ON)
-add_compile_definitions($<$<COMPILE_LANGUAGE:CXX>:POINTERHOLDER_TRANSITION=4>)
 if(ENABLE_QTC)
   set(ENABLE_QTC_ARG)
 2025-02-15  Jay Berkenbilt  <ejb@ql.org>
+	* Disable PointerHolder by default.
+
+2025-02-15  Jay Berkenbilt  <ejb@ql.org>
+
 	* 11.10.1: release
 	* Detect cygwin as Windows for fix-qdf tests that don't work on
@@ -21,7 +21,6 @@
 #define BUFFER_HH
 #include <qpdf/DLL.h>
-#include <qpdf/PointerHolder.hh> // unused -- remove in qpdf 12 (see #785)
 #include <cstddef>
 #include <memory>
@@ -26,7 +26,6 @@
 // merging large numbers of files.
 #include <qpdf/InputSource.hh>
-#include <qpdf/PointerHolder.hh> // unused -- remove in qpdf 12 (see #785)
 #include <memory>
@@ -21,7 +21,6 @@
 #define QPDF_INPUTSOURCE_HH
 #include <qpdf/DLL.h>
-#include <qpdf/PointerHolder.hh> // unused -- remove in qpdf 12 (see #785)
 #include <qpdf/Types.h>
 #include <cstdio>
@@ -30,7 +30,6 @@
 // is also a good reason not to use this as a general-purpose JSON package.
 #include <qpdf/DLL.h>
-#include <qpdf/PointerHolder.hh> // unused -- remove in qpdf 12 (see #785)
 #include <qpdf/Types.h>
 #include <functional>
@@ -37,7 +37,6 @@
 #define PIPELINE_HH
 #include <qpdf/DLL.h>
-#include <qpdf/PointerHolder.hh> // unused -- remove in qpdf 12 (see #785)
 #include <memory>
 #include <string>
@@ -31,7 +31,6 @@
 #include <qpdf/Buffer.hh>
 #include <qpdf/Pipeline.hh>
-#include <qpdf/PointerHolder.hh> // unused -- remove in qpdf 12 (see #785)
 #include <memory>
 #include <string>
@@ -23,7 +23,6 @@
 #include <qpdf/Pipeline.hh>
 #include <qpdf/Pl_Buffer.hh>
-#include <qpdf/PointerHolder.hh> // unused -- remove in qpdf 12 (see #785)
 #include <qpdf/QPDFObjectHandle.hh>
 #include <qpdf/QPDFTokenizer.hh>
@@ -26,18 +26,12 @@
 #define POINTERHOLDER_IS_SHARED_POINTER
 #ifndef POINTERHOLDER_TRANSITION
-
-// #define POINTERHOLDER_TRANSITION 0 to suppress this warning, and see below.
-// See also https://qpdf.readthedocs.io/en/stable/design.html#smart-pointers
-# warning "POINTERHOLDER_TRANSITION is not defined -- see qpdf/PointerHolder.hh"
-
-// undefined = define as 0 and issue a warning
 // 0 = no deprecation warnings, backward-compatible API
 // 1 = make PointerHolder<T>(T*) explicit
 // 2 = warn for use of getPointer() and getRefcount()
 // 3 = warn for all use of PointerHolder
 // 4 = don't define PointerHolder at all
-# define POINTERHOLDER_TRANSITION 0
+# define POINTERHOLDER_TRANSITION 4
 #endif // !defined(POINTERHOLDER_TRANSITION)
 #if POINTERHOLDER_TRANSITION < 4
@@ -50,15 +44,19 @@
 // interface and is mutually assignable with std::shared_ptr. Code
 // that uses containers of PointerHolder will require adjustment.
+// In qpdf 11, a backward-compatible PointerHolder was provided with a
+// warning if POINTERHOLDER_TRANSITION was not defined. Starting in
+// qpdf 12, PointerHolder is absent if POINTERHOLDER_TRANSITION is not
+// defined. In a future version of qpdf, PointerHolder will be removed
+// outright if it becomes inconvenient to keep it around.
+
 // *** HOW TO TRANSITION ***
 // The symbol POINTERHOLDER_TRANSITION can be defined to help you
 // transition your code away from PointerHolder. You can define it
 // before including any qpdf header files or including its definition
 // in your build configuration. If not defined, it automatically gets
-// defined to 0 (with a warning), which enables full backward
-// compatibility. That way, you don't have to take action for your
-// code to continue to work.
+// defined to 4, which excludes PointerHolder entirely.
 // If you want to work gradually to transition your code away from
 // PointerHolder, you can define POINTERHOLDER_TRANSITION and fix the
@@ -123,7 +121,8 @@
 // POINTERHOLDER_TRANSITION = 4
 //
-// Suppress definition of the PointerHolder<T> type entirely.
+// Suppress definition of the PointerHolder<T> type entirely. This is
+// the default behavior starting with qpdf 12.
 // CONST BEHAVIOR
 # Generated by generate_auto_job
-CMakeLists.txt 589283144c7c941ef96a12a7e57c354ec24d845657c919996867c60330501550
+CMakeLists.txt f0819695e4867e4f4389d38b0c124e79aa3ec9ace50f16ad8c751ff7f1ec6690
 generate_auto_job f64733b79dcee5a0e3e8ccc6976448e8ddf0e8b6529987a66a7d3ab2ebc10a86
 include/qpdf/auto_job_c_att.hh 4c2b171ea00531db54720bf49a43f8b34481586ae7fb6cbf225099ee42bc5bb4
 include/qpdf/auto_job_c_copy_att.hh 50609012bff14fd82f0649185940d617d05d530cdc522185c7f3920a561ccb42
@@ -860,8 +860,8 @@ modification of code.
 The ``POINTERHOLDER_TRANSITION`` preprocessor symbol was introduced in
 qpdf 10.6.0 to help people transition from ``PointerHolder`` to
-``std::shared_ptr``. If you don't define this, you will get a compiler
-warning. Defining it to any value will suppress the warning. An
+``std::shared_ptr``. If you don't define this, ``PointerHolder`` will
+be completely excluded from the API (starting with qpdf 12).An
 explanation appears below of the different possible values for this
 symbol and what they mean.
@@ -1003,7 +1003,7 @@ without consulting this manual.
      - meaning
    - - undefined
-     - Same as ``0`` but issues a warning
+     - Same as ``4``: ``PointerHolder`` is not defined.
    - - ``0``
      - Provide a backward compatible ``PointerHolder`` and suppress
@@ -29,6 +29,18 @@ Planned changes for future 12.x (subject to change):
 .. x.y.z: not yet released
+12.0.0: not yet released
+  - Build Changes
+
+    - If ``POINTERHOLDER_TRANSITION`` is not defined, define it to
+      ``4``, which completely removes ``PointerHolder`` from the API.
+      Stop including it from any headers that used to include it. This
+      means code that hasn't completed its ``PointerHolder``
+      transition will get errors unless it defines
+      ``POINTERHOLDER_TRANSITION``, and any file that uses
+      ``PointerHolder`` will have to explicitly include it rather than
+      relying on other headers to bring it along.
+
 11.10.1: February 15, 2025
   - Build fixes
-#ifndef POINTERHOLDER_TRANSITION
-# define POINTERHOLDER_TRANSITION 4
-#endif
-
 #include <qpdf/QPDF.hh>
 #include <iostream>