pk.h.in: add module descriptions and impl options

1 files changed, 104 insertions, 11 deletions

diff --git a/pk.h.in b/pk.h.in
index af36589..de28ee0 100644
--- a/pk.h.in
+++ b/pk.h.in
@@ -1,27 +1,120 @@
 // vim: tw=80
-/******************************************************************************
+/*******************************************************************************
 * PK Single-Header-Library V@@PK_VERSION@@
 *
 * Author:           Jonathan Bradley
 * Copyright:        © 2024-@@YEAR@@ Jonathan Bradley
 * Description:
 *
-*******************************************************************************
+* A collection of useful programming tools, available for C and C++ as a
+*  single-header file. To enable, in ONE single C or C++ file, declare
+*  PK_IMPL_ALL before including pk.h.
+*
+* Example:
+*
+* pk.h.include.c
+* ``` c
+* #define PK_IMPL_ALL
+* #include "pk.h"
+* ```
+*
+* It is also possible to enable modules ad-hoc by defining each IMPL
+*  individually:
+*
+* pk.h.include.c
+* ``` c
+* # define PK_IMPL_MEM_TYPES
+* # define PK_IMPL_MEM
+* # define PK_IMPL_STR
+* # define PK_IMPL_EV
+* #include "pk.h"
+* ```
+*
+********************************************************************************
 * pkmacros.h:
 *
-*******************************************************************************
-* pkmem-types.h:
+* Provides a set of useful macros for a variety of uses.
+*
+* The macros PK_LOG* provide simple logging utilities. These can be overridden
+*  by providing your own implementations of each and defining PK_LOG_OVERRIDE
+*  before including pk.h Note that each of these are no-op'd if NDEBUG is
+*  defined.
+*
+* The TypeSafeInt_H and TypeSafeInt_B macros provide a way to define
+*  type-specific integers, implemented via enums.
+*
+********************************************************************************
+* pkmem-types.h: def PK_IMPL_MEM_TYPES before including pk.h to enable ad-hoc.
+*
+* Provides the types needed by pkmem, as well as a generic pk_handle featuring a
+*  bucket+item indexing system.
+*
+********************************************************************************
+* pkmem.h: def PK_IMPL_MEM before including pk.h to enable ad-hoc.
+*
+* A bucketed memory manager. Allows the creation and management of up to a well
+*  known number of buckets. While this is thread-safe, the threading safety is
+*  a Grug implementation via a single mutex. PRs welcome.
+*
+* The following definitions (shown with defaults) can be overridden:
+* PK_DEFAULT_BUCKET_SIZE     256MB (used when bkt is NULL on first call)
+* PK_MINIMUM_ALIGNMENT       1
+* PK_MAXIMUM_ALIGNMENT       64
+* PK_MAX_BUCKET_COUNT        8
+*
+* For debugging purposes, define the following:
+* PK_MEMORY_DEBUGGER : enables a tracking system for all allocs and frees to
+*  ensure bucket validity and consistency.
+* PK_MEMORY_FORCE_MALLOC : completely disables pkmem and its debugging features
+*  in favor of directly using malloc and free. Useful for out-of-bounds
+*  checking.
+*
+********************************************************************************
+* pkstr.h: def PK_IMPL_STR before including pk.h to enable ad-hoc.
+*
+* Provides a simple string structure, allowing the user to track the string
+*  length and reserved buffer length. Limites max string length to uint32_t max
+*  size, which is roughly 4GB.
+*
+* Tip: set reserved to 0 for compile-time strings as well as for strings alloc'd
+*  in a larger buffer (such as bulk-loaded data).
+*
+********************************************************************************
+* pkev.h: def PK_IMPL_EV before including pk.h to enable ad-hoc.
+*
+* Provides a simple event callback system. While the _init and _teardown
+*  functions are NOT thread-safe, the _register and _emit functions are.
+*  Note: uses malloc.
+*
+* Each mgr is stored contiguously with its data. Consider the following layout:
+* [[mgr][ev 0][ev 1][..][ev N][ev 1 cb array][ev 2 cb array][..][ev N cb array]]
+*
+* The following definitions (shown with defaults) can be overridden:
+* PK_EV_INIT_MGR_COUNT       1
+* PK_EV_INIT_EV_COUNT        16
+* PK_EV_INIT_CB_COUNT        8
+* PK_EV_GROW_RATIO           1.5
 *
-*******************************************************************************
-* pkmem.h:
+* The number of evs and cbs (per ev) is stored as a uint8_t, so a hard-limit of
+*  255 is to be observed for each. The number of mgrs is stored as a uint64_t.
 *
-*******************************************************************************
-* pkstr.h:
+* Note that PK_EV_GROW_RATIO is used in two scenarios:
+*  1. when registering an ev on a full mgr
+*  2. when registering a cb on a full ev
+* The grow ratio is applied to the ev count and cb count in their respective
+*  scenarios. This causes a new allocation for the entire mgr. The existing
+*  mgr and its evs and cbs are copied to the new larger buffer space.
+*  Explicitly, the number of mgrs does not grow dynamically. Use
+*  PK_EV_INIT_MGR_COUNT to control the number of mgrs.
 *
-*******************************************************************************
-* pkev.h:
+* Note that increasing PK_EV_INIT_MGR_COUNT isn't recommended, but you may
+*  consider doing so if you have specific size or contiguity requirements. For
+*  example, you could -DPK_EV_INIT_EV_COUNT=1 to reduce the memory footprint of
+*  each event/mgr, and simply create a new mgr for each needed event. Be aware
+*  that in this provided scenario a given mgr will still grow if a second EV is
+*  registered.
 *
-******************************************************************************/
+*******************************************************************************/
 
 #define PK_VERSION "@@PK_VERSION@@"