all: misc updates

src/util/xspan.cpp

@@ -33,7 +33,7 @@ XSPAN_NAMESPACE_BEGIN
 // debugging stats
 struct XSpanStats {
     upx_std_atomic(size_t) check_range_counter;
-    // doctest checks will set these:
+    // these normally will be zero, but doctest checks will populate them
     upx_std_atomic(size_t) fail_nullptr;
     upx_std_atomic(size_t) fail_nullbase;
     upx_std_atomic(size_t) fail_not_same_base;
@@ -70,15 +70,15 @@ void xspan_fail_range_range() {
     throwCantPack("xspan_check_range: pointer out of range; take care!");
 }
 
-void xspan_check_range(const void *p, const void *base, ptrdiff_t size_in_bytes) {
-    if very_unlikely (p == nullptr)
+void xspan_check_range(const void *ptr, const void *base, ptrdiff_t size_in_bytes) {
+    xspan_stats.check_range_counter += 1;
+    if very_unlikely (ptr == nullptr)
         xspan_fail_range_nullptr();
     if very_unlikely (base == nullptr)
         xspan_fail_range_nullbase();
-    ptrdiff_t off = (const charptr) p - (const charptr) base;
+    ptrdiff_t off = (const charptr) ptr - (const charptr) base;
     if very_unlikely (off < 0 || off > size_in_bytes || size_in_bytes > UPX_RSIZE_MAX)
         xspan_fail_range_range();
-    xspan_stats.check_range_counter += 1;
     NO_fprintf(stderr, "xspan_check_range done\n");
 }
 

src/util/xspan.h

@@ -43,7 +43,7 @@
 #define XSPAN_CONFIG_ENABLE_IMPLICIT_CONVERSION 0
 #endif
 // allow automatic conversion PtrOrSpanOrNull => PtrOrSpan => Span (with run-time checks)
-// choose between compile-time safety vs. possible run-time errors
+// choose between compile-time safety vs. possible run-time exceptions
 #ifndef XSPAN_CONFIG_ENABLE_SPAN_CONVERSION
 #define XSPAN_CONFIG_ENABLE_SPAN_CONVERSION 1
 #endif

src/util/xspan_impl.h

@@ -42,13 +42,13 @@
 XSPAN_NAMESPACE_BEGIN
 
 // HINT: set env-var "UPX_DEBUG_DOCTEST_DISABLE=1" for improved debugging experience
-noinline void xspan_fail_nullptr();
-noinline void xspan_fail_nullbase();
-noinline void xspan_fail_not_same_base();
-noinline void xspan_fail_range_nullptr();
-noinline void xspan_fail_range_nullbase();
-noinline void xspan_fail_range_range();
-void xspan_check_range(const void *p, const void *base, ptrdiff_t size_in_bytes);
+noinline void xspan_fail_nullptr(void);
+noinline void xspan_fail_nullbase(void);
+noinline void xspan_fail_not_same_base(void);
+noinline void xspan_fail_range_nullptr(void);
+noinline void xspan_fail_range_nullbase(void);
+noinline void xspan_fail_range_range(void);
+void xspan_check_range(const void *ptr, const void *base, ptrdiff_t size_in_bytes);
 
 // help constructor to distinguish between number of elements and bytes
 struct XSpanCount {

src/util/xspan_impl_common.h

@@ -113,6 +113,7 @@ forceinline ~CSelf() noexcept {}
 #endif
     noinline void invalidate() {
         assertInvariants();
+        // poison the pointer
         ptr = (pointer) (upx_uintptr_t) 16; // point to non-null invalid address
         // ptr = (pointer) (void *) &ptr; // point to self
         base = ptr;

src/util/xspan_impl_ptr.h

@@ -59,6 +59,8 @@ private:
 
 public:
 #if XSPAN_CONFIG_ENABLE_IMPLICIT_CONVERSION || 1
+    // Ptr always provides automatic conversion to underlying type because
+    // it has limited functionality
     operator pointer() const noexcept { return ptr; }
 #endif
 
@@ -75,6 +77,7 @@ public:
 #endif
     noinline void invalidate() {
         assertInvariants();
+        // poison the pointer
         ptr = (pointer) (upx_uintptr_t) 16; // point to non-null invalid address
         // ptr = (pointer) (void *) &ptr; // point to self
         assertInvariants();