More API polishing. Really starting to look clean and enforces a lot of good habits.

Author: kyle-github

src/include/ptk_buf.h

@@ -120,7 +120,7 @@ extern ptk_err ptk_buf_set_end(ptk_buf *buf, buf_size_t end);
  */
 extern ptk_err ptk_buf_move_block(ptk_buf *buf, buf_size_t new_position);
 
-/* no ptk_buf_free() because that it taken care of by ptk_alloc() */
+/* Use ptk_local_free() to free buffers allocated with ptk_buf_alloc() */
 
 //=============================================================================
 // SIMPLE BYTE ACCESS API

src/include/ptk_mem.h

@@ -171,22 +171,48 @@ extern void ptk_local_free_impl(const char *file, int line, void **ptr_ref);
 
 
 typedef struct ptk_shared_handle {
-    uint64_t value;  // Opaque handle value
+    uintptr_t value;  // Opaque handle value
 } ptk_shared_handle_t;
 
 #define PTK_SHARED_INVALID_HANDLE ((ptk_shared_handle_t){0})
 #define PTK_SHARED_IS_VALID(h) ((h).value != 0)
 #define PTK_SHARED_HANDLE_EQUAL(a,b) ((a).value == (b).value)
 
-#define ptk_shared_create(ptr) ptk_shared_create_impl(__FILE__, __LINE__, ptr)
-extern ptk_shared_handle_t ptk_shared_create_impl(const char *file, int line, void *ptr);
-
+/**
+ * @brief Initialize the shared memory subsystem.
+ *
+ * @return ptk_err status code
+ * @retval PTK_OK on success
+ */
 extern ptk_err ptk_shared_init(void);
+
+/**
+ * @brief Shut down the shared memory subsystem.
+ *
+ * @return ptk_err status code
+ * @retval PTK_OK on success
+ */
 extern ptk_err ptk_shared_shutdown(void);
 
-extern void *ptk_shared_acquire(ptk_shared_handle_t handle);
-extern ptk_err ptk_shared_realloc(ptk_shared_handle_t handle, size_t new_size);  // reuses the existing handle.
-extern ptk_err ptk_shared_release(ptk_shared_handle_t handle);
+
+/**
+ * @brief Allocate a shared memory block.
+ *
+ * @param size Size of the memory block to allocate
+ * @param destructor Optional destructor function for the memory block
+ * @return ptk_shared_handle_t Handle to the allocated memory, or PTK_SHARED_INVALID_HANDLE on failure
+ */
+#define ptk_shared_alloc(size, destructor) ptk_shared_alloc_impl(__FILE__, __LINE__, size, destructor)
+extern ptk_shared_handle_t ptk_shared_alloc_impl(const char *file, int line, size_t size, void (*destructor)(void *ptr));
+
+#define ptk_shared_realloc(handle, new_size) ptk_shared_realloc_impl(__FILE__, __LINE__, handle, new_size)
+extern ptk_err ptk_shared_realloc_impl(const char *file, int line, ptk_shared_handle_t handle, size_t new_size);  // reuses the existing handle.
+
+#define ptk_shared_acquire(handle, timeout) ptk_shared_acquire_impl(__FILE__, __LINE__, handle, timeout)
+extern void *ptk_shared_acquire_impl(const char *file, int line, ptk_shared_handle_t handle, ptk_time_ms timeout);
+
+#define ptk_shared_release(handle) ptk_shared_release_impl(__FILE__, __LINE__, handle)
+extern ptk_err ptk_shared_release_impl(const char *file, int line, ptk_shared_handle_t handle);
 
 /**
  * @brief Macro for safely using shared memory with automatic acquire/release
@@ -195,22 +221,26 @@ extern ptk_err ptk_shared_release(ptk_shared_handle_t handle);
  * handling acquire/release operations and providing error handling.
  * 
  * Usage:
- * use_shared(handle, my_struct_t *obj) {
+ * use_shared(handle, timeout_ms, my_struct_t *obj) {
  *     // Code that uses obj - obj is automatically cast to the correct type
  *     obj->field = value;
  * } on_shared_fail {
- *     // Error handling code - runs if acquire fails
+ *     // Error handling code - runs if acquire fails or times out
  *     error("Failed to acquire shared memory");
  * }
  * 
  * @param handle The shared memory handle to acquire
+ * @param timeout_ms Timeout in milliseconds (use PTK_TIME_WAIT_FOREVER or PTK_TIME_NO_WAIT)
  * @param declaration The typed pointer declaration (e.g., "my_struct_t *obj")
+ * 
+ * NOTE: ptk_shared_release_impl must be called even if the return value is NULL, to avoid leaks.
+ *       The macro ensures this happens automatically.
  */
-#define use_shared(handle, declaration) \
+#define use_shared(handle, timeout_ms, declaration) \
     for (int _ptk_shared_once = 0; _ptk_shared_once < 1; _ptk_shared_once++) \
-        for (void *_ptk_shared_raw_ptr = ptk_shared_acquire(handle); \
+        for (void *_ptk_shared_raw_ptr = ptk_shared_acquire_impl(__FILE__, __LINE__, handle, timeout_ms); \
              _ptk_shared_once < 1; \
-             _ptk_shared_once++, (_ptk_shared_raw_ptr ? ptk_shared_release(handle) : (void)0)) \
+             _ptk_shared_once++, ptk_shared_release_impl(__FILE__, __LINE__, handle)) \
             if (_ptk_shared_raw_ptr != NULL) \
                 for (declaration = (typeof(declaration))_ptk_shared_raw_ptr; \
                      _ptk_shared_raw_ptr != NULL; \

src/include/ptk_os_thread.h

@@ -28,117 +28,172 @@
 #include <stdint.h>
 #include <stddef.h>
 #include <stdbool.h>
-
 // Forward declarations to break circular dependencies
 typedef enum ptk_err ptk_err;
+typedef struct ptk_shared_handle ptk_shared_handle_t;
 typedef int64_t ptk_time_ms;
 
+// Timeout constants (from ptk_utils.h)
+#define PTK_TIME_WAIT_FOREVER (INT64_MAX)
+#define PTK_TIME_NO_WAIT (INT64_MIN)
+
 #if defined(_WIN32) && defined(_MSC_VER)
 #define ptk_thread_local __declspec(thread)
 #else
 #define ptk_thread_local __thread
 #endif
 
 
+/* Mutex and condition variable types removed from public API.
+ * Use shared memory handles for synchronization instead:
+ * - Data protection: use_shared() macro provides automatic synchronization
+ * - Thread communication: ptk_thread_signal() and ptk_thread_wait()
+ * - OS-native mutexes used internally by shared memory implementation only
+ */
+
 /**
- * @brief Forward declaration of a mutex type.
+ * @brief Thread handle type (uses shared memory for safe cross-thread access)
  */
-typedef struct ptk_mutex ptk_mutex;
+typedef ptk_shared_handle_t ptk_thread_handle_t;
 
 /**
- * @brief Forward declaration of a condition variable type.
+ * @brief No parent constant for root threads
  */
-typedef struct ptk_cond_var ptk_cond_var;
+#define PTK_THREAD_NO_PARENT PTK_SHARED_INVALID_HANDLE
 
 /**
- * @brief Forward declaration of a thread type.
+ * @brief Thread signal types for unified signaling API
+ */
+typedef enum {
+    PTK_THREAD_SIGNAL_WAKEUP,      // General wake-up signal
+    PTK_THREAD_SIGNAL_ABORT,       // Request graceful shutdown  
+    PTK_THREAD_SIGNAL_TERMINATE,   // Force immediate termination
+    PTK_THREAD_SIGNAL_CHILD_DIED   // Child death notification (automatic)
+} ptk_thread_signal_t;
+
+/* Public mutex and condition variable APIs removed.
+ * Synchronization handled by shared memory system:
+ * 
+ * Instead of mutexes, use shared memory access patterns:
+ *   use_shared(data_handle, timeout, my_data_t *data) {
+ *       // Automatically synchronized access to data
+ *   } on_shared_fail {
+ *       // Handle timeout or failure
+ *   }
+ *
+ * Instead of condition variables, use thread signals:
+ *   ptk_thread_signal(worker_thread);  // Wake up waiting thread
+ *   ptk_thread_wait(handle, timeout);  // Wait for signal
  */
-typedef struct ptk_thread ptk_thread;
 
 //============================
-// Mutex Functions
+// Thread Functions
 //============================
 
 /**
- * @brief Creates a new recursive mutex.
+ * @brief Function type for thread entry points.
  *
- * @param allocator The allocator to use for creating the mutex
- * @return Pointer to the newly created mutex, or NULL on failure
+ * @param data Shared memory handle containing user data for the thread.
  */
-extern ptk_mutex *ptk_mutex_create(void);
+typedef void (*ptk_thread_func)(ptk_shared_handle_t data);
 
 /**
- * @brief Attempts to lock the mutex, optionally waiting for a timeout.
+ * @brief Creates and starts a new thread with parent-child relationship.
+ *
+ * Child threads automatically register with parent and signal parent when they die.
+ * Use PTK_THREAD_NO_PARENT for root threads.
  *
- * @param mutex Pointer to the mutex.
- * @param timeout_ms Timeout in milliseconds. Use PTK_TIME_NO_WAIT or PTK_TIME_WAIT_FOREVER for special cases.
- * @return Error code.
+ * @param parent Parent thread handle, or PTK_THREAD_NO_PARENT for root threads
+ * @param func Entry point for the thread function
+ * @param data User data to pass to the thread function (shared memory handle)
+ * @return Thread handle for the new thread, or PTK_SHARED_INVALID_HANDLE on failure
  */
-extern ptk_err ptk_mutex_wait_lock(ptk_mutex *mutex, ptk_time_ms timeout_ms);
+extern ptk_thread_handle_t ptk_thread_create(ptk_thread_handle_t parent,
+                                             ptk_thread_func func, 
+                                             ptk_shared_handle_t data);
 
 /**
- * @brief Unlocks the previously locked mutex.
+ * @brief Get the current thread's handle.
  *
- * @param mutex Pointer to the mutex.
- * @return Error code.
+ * @return Handle for the calling thread
  */
-extern ptk_err ptk_mutex_unlock(ptk_mutex *mutex);
-
-//============================
-// Condition Variable Functions
-//============================
+extern ptk_thread_handle_t ptk_thread_self(void);
 
 /**
- * @brief Creates a condition variable.
+ * @brief Wait for signals or timeout (calling thread waits for itself).
  *
- * @param allocator The allocator to use for creating the condition variable
- * @return Pointer to the created condition variable, or NULL on failure
+ * The calling thread waits until signaled or timeout occurs. Socket operations
+ * (like ptk_tcp_accept) also wake up on any signal for responsive server loops.
+ *
+ * @param timeout_ms Timeout in milliseconds 
+ * @return PTK_OK on timeout, PTK_SIGNAL if signaled (check ptk_thread_get_last_signal())
  */
-extern ptk_cond_var *ptk_cond_var_create(void);
+extern ptk_err ptk_thread_wait(ptk_time_ms timeout_ms);
 
 /**
- * @brief Signals the condition variable, waking one waiting thread.
+ * @brief Send a signal to a thread.
+ *
+ * Signals cause the target thread to wake up from ptk_thread_wait() or socket
+ * operations like ptk_tcp_accept(). The thread can check the signal type.
  *
- * @param cond_var Pointer to the condition variable.
- * @return Error code.
+ * @param handle Thread handle to signal
+ * @param signal_type Type of signal to send
+ * @return Error code
  */
-extern ptk_err ptk_cond_var_signal(ptk_cond_var *cond_var);
+extern ptk_err ptk_thread_signal(ptk_thread_handle_t handle, ptk_thread_signal_t signal_type);
 
 /**
- * @brief Waits for the condition variable to be signaled.
+ * @brief Get the last signal received by the calling thread.
+ *
+ * Call this after ptk_thread_wait() returns PTK_SIGNAL to determine what signal was received.
  *
- * @param cond_var Pointer to the condition variable.
- * @param mutex Pointer to an already locked mutex that will be released during the wait.
- * @param timeout_ms Timeout in milliseconds. Use THREAD_NO_WAIT or THREAD_WAIT_FOREVER for special cases.
- * @return Error code.
+ * @return The last signal type received, or PTK_THREAD_SIGNAL_WAKEUP if none
  */
-extern ptk_err ptk_cond_var_wait(ptk_cond_var *cond_var, ptk_mutex *mutex, ptk_time_ms timeout_ms);
+extern ptk_thread_signal_t ptk_thread_get_last_signal(void);
 
 //============================
-// Thread Functions
+// Parent-Child Thread Management
 //============================
 
 /**
- * @brief Function type for thread entry points.
+ * @brief Get the parent thread handle.
+ *
+ * @param thread Thread handle to query (use ptk_thread_self() for current thread)
+ * @return Parent thread handle, or PTK_THREAD_NO_PARENT if no parent
+ */
+extern ptk_thread_handle_t ptk_thread_get_parent(ptk_thread_handle_t thread);
+
+/**
+ * @brief Count the number of child threads.
  *
- * @param data Pointer to user data passed to the thread.
+ * Child threads are automatically tracked. This returns the current count.
+ *
+ * @param parent Parent thread handle
+ * @return Number of active child threads
  */
-typedef void (*ptk_thread_func)(void *data);
+extern int ptk_thread_count_children(ptk_thread_handle_t parent);
 
 /**
- * @brief Creates and starts a new thread.
+ * @brief Signal all child threads.
+ *
+ * Sends the same signal to all children of the specified parent thread.
+ * Useful for coordinated shutdown or other broadcast operations.
  *
- * @param func Entry point for the thread function.
- * @param data User data to pass to the thread function.
- * @return Pointer to the created thread handle, or NULL on failure
+ * @param parent Parent thread handle
+ * @param signal_type Signal to send to all children
+ * @return Error code
  */
-extern ptk_thread *ptk_thread_create(ptk_thread_func func, void *data);
+extern ptk_err ptk_thread_signal_all_children(ptk_thread_handle_t parent, ptk_thread_signal_t signal_type);
 
 /**
- * @brief Waits for the specified thread to complete.
+ * @brief Clean up dead child threads.
+ *
+ * Attempts to release handles for child threads that have died. Uses timeout
+ * to avoid blocking. Call with PTK_TIME_NO_WAIT for immediate cleanup only.
  *
- * @param thread Thread to join.
- * @return Error code.
+ * @param parent Parent thread handle
+ * @param timeout_ms Maximum time to wait for cleanup
+ * @return Error code
  */
-extern ptk_err ptk_thread_join(ptk_thread *thread);
+extern ptk_err ptk_thread_cleanup_dead_children(ptk_thread_handle_t parent, ptk_time_ms timeout_ms);