refactor(test): comprehensive unit test refactoring

include/libipc/buffer.h

@@ -17,14 +17,16 @@ class IPC_EXPORT buffer {
     buffer();
 
     buffer(void* p, std::size_t s, destructor_t d);
-    buffer(void* p, std::size_t s, destructor_t d, void* additional);
+    // mem_to_free: pointer to be passed to destructor (if different from p)
+    // Use case: when p points into a larger allocated block that needs to be freed
+    buffer(void* p, std::size_t s, destructor_t d, void* mem_to_free);
     buffer(void* p, std::size_t s);
 
     template <std::size_t N>
-    explicit buffer(byte_t const (& data)[N])
+    explicit buffer(byte_t (& data)[N])
         : buffer(data, sizeof(data)) {
     }
-    explicit buffer(char const & c);
+    explicit buffer(char & c);
 
     buffer(buffer&& rhs);
     ~buffer();

include/libipc/shm.h

@@ -17,8 +17,30 @@ enum : unsigned {
 
 IPC_EXPORT id_t         acquire(char const * name, std::size_t size, unsigned mode = create | open);
 IPC_EXPORT void *       get_mem(id_t id, std::size_t * size);
+
+// Release shared memory resource and clean up disk file if reference count reaches zero.
+// This function decrements the reference counter. When the counter reaches zero, it:
+// 1. Unmaps the shared memory region
+// 2. Removes the backing file from disk (shm_unlink on POSIX)
+// 3. Frees the id structure
+// After calling this function, the id becomes invalid and must not be used again.
+// Returns: The reference count before decrement, or -1 on error.
 IPC_EXPORT std::int32_t release(id_t id) noexcept;
+
+// Release shared memory resource and force cleanup of disk file.
+// This function calls release(id) internally, then unconditionally attempts to
+// remove the backing file. WARNING: Do NOT call this after release(id) on the
+// same id, as the id is already freed by release(). Use this function alone,
+// not in combination with release().
+// Typical use case: Force cleanup when you want to ensure the disk file is removed
+// regardless of reference count state.
 IPC_EXPORT void         remove (id_t id) noexcept;
+
+// Remove shared memory backing file by name.
+// This function only removes the disk file and does not affect any active memory
+// mappings or id structures. Use this for cleanup of orphaned files or for explicit
+// file removal without affecting runtime resources.
+// Safe to call at any time, even if shared memory is still in use elsewhere.
 IPC_EXPORT void         remove (char const * name) noexcept;
 
 IPC_EXPORT std::int32_t get_ref(id_t id);

src/libipc/buffer.cpp

@@ -38,16 +38,16 @@ buffer::buffer(void* p, std::size_t s, destructor_t d)
     : p_(p_->make(p, s, d, nullptr)) {
 }
 
-buffer::buffer(void* p, std::size_t s, destructor_t d, void* additional)
-    : p_(p_->make(p, s, d, additional)) {
+buffer::buffer(void* p, std::size_t s, destructor_t d, void* mem_to_free)
+    : p_(p_->make(p, s, d, mem_to_free)) {
 }
 
 buffer::buffer(void* p, std::size_t s)
     : buffer(p, s, nullptr) {
 }
 
-buffer::buffer(char const & c)
-    : buffer(const_cast<char*>(&c), 1) {
+buffer::buffer(char & c)
+    : buffer(&c, 1) {
 }
 
 buffer::buffer(buffer&& rhs)

src/libipc/platform/linux/condition.h

@@ -27,7 +27,7 @@ class condition : public sync::obj_impl<a0_cnd_t> {
                 return false;
             }
         } else {
-            auto ts = detail::make_timespec(tm);
+            auto ts = linux_::detail::make_timespec(tm);
             int eno = A0_SYSERR(a0_cnd_timedwait(native(), static_cast<a0_mtx_t *>(mtx.native()), {ts}));
             if (eno != 0) {
                 if (eno != ETIMEDOUT) {

src/libipc/platform/linux/get_wait_time.h

@@ -10,6 +10,7 @@
 #include "a0/err_macro.h"
 
 namespace ipc {
+namespace linux_ {
 namespace detail {
 
 inline bool calc_wait_time(timespec &ts, std::uint64_t tm /*ms*/) noexcept {
@@ -43,4 +44,5 @@ inline timespec make_timespec(std::uint64_t tm /*ms*/) noexcept(false) {
 }
 
 } // namespace detail
+} // namespace linux_
 } // namespace ipc

src/libipc/platform/linux/mutex.h

@@ -25,7 +25,7 @@ class robust_mutex : public sync::obj_impl<a0_mtx_t> {
     bool lock(std::uint64_t tm) noexcept {
         if (!valid()) return false;
         for (;;) {
-            auto ts = detail::make_timespec(tm);
+            auto ts = linux_::detail::make_timespec(tm);
             int eno = A0_SYSERR(
                 (tm == invalid_value) ? a0_mtx_lock(native()) 
                                       : a0_mtx_timedlock(native(), {ts}));
@@ -56,7 +56,7 @@ class robust_mutex : public sync::obj_impl<a0_mtx_t> {
 
     bool try_lock() noexcept(false) {
         if (!valid()) return false;
-        int eno = A0_SYSERR(a0_mtx_timedlock(native(), {detail::make_timespec(0)}));
+        int eno = A0_SYSERR(a0_mtx_timedlock(native(), {linux_::detail::make_timespec(0)}));
         switch (eno) {
         case 0:
             return true;

src/libipc/platform/posix/condition.h

@@ -115,7 +115,7 @@ class condition {
             }
             break;
         default: {
-                auto ts = detail::make_timespec(tm);
+                auto ts = posix_::detail::make_timespec(tm);
                 int eno;
                 if ((eno = ::pthread_cond_timedwait(cond_, static_cast<pthread_mutex_t *>(mtx.native()), &ts)) != 0) {
                     if (eno != ETIMEDOUT) {

src/libipc/platform/posix/get_wait_time.h

@@ -10,6 +10,7 @@
 #include "libipc/utility/log.h"
 
 namespace ipc {
+namespace posix_ {
 namespace detail {
 
 inline bool calc_wait_time(timespec &ts, std::uint64_t tm /*ms*/) noexcept {
@@ -36,4 +37,5 @@ inline timespec make_timespec(std::uint64_t tm /*ms*/) noexcept(false) {
 }
 
 } // namespace detail
+} // namespace posix_
 } // namespace ipc

src/libipc/platform/posix/mutex.h

@@ -196,7 +196,7 @@ class mutex {
     bool lock(std::uint64_t tm) noexcept {
         if (!valid()) return false;
         for (;;) {
-            auto ts = detail::make_timespec(tm);
+            auto ts = posix_::detail::make_timespec(tm);
             int eno = (tm == invalid_value) 
                 ? ::pthread_mutex_lock(mutex_) 
                 : ::pthread_mutex_timedlock(mutex_, &ts);
@@ -230,7 +230,7 @@ class mutex {
 
     bool try_lock() noexcept(false) {
         if (!valid()) return false;
-        auto ts = detail::make_timespec(0);
+        auto ts = posix_::detail::make_timespec(0);
         int eno = ::pthread_mutex_timedlock(mutex_, &ts);
         switch (eno) {
         case 0:

src/libipc/platform/posix/semaphore_impl.h

@@ -88,7 +88,7 @@ class semaphore {
                 return false;
             }
         } else {
-            auto ts = detail::make_timespec(tm);
+            auto ts = posix_::detail::make_timespec(tm);
             if (::sem_timedwait(h_, &ts) != 0) {
                 if (errno != ETIMEDOUT) {
                     ipc::error("fail sem_timedwait[%d]: tm = %zd, tv_sec = %ld, tv_nsec = %ld\n",