doomgram

.vscode/settings.json

@@ -1,7 +1,7 @@
 {
   "[c]": {
     "editor.insertSpaces": true,
-    "editor.rulers": [ 60, 76 ],
+    "editor.rulers": [ 60, 64, 68, 72, 76 ],
     "editor.tabSize": 4,
   },
   "[cpp]": {

CMakeLists.txt

@@ -5,7 +5,7 @@
 # Purpose:  Top-level CMake lists file for Diagnosticism
 #
 # Created:  23rd November 2024
-# Updated:  15th January 2025
+# Updated:  5th February 2025
 #
 # ######################################################################## #
 
@@ -60,7 +60,7 @@ set(PROJECT_VERSION "${PROJECT_VERSION_MAJOR}.${PROJECT_VERSION_MINOR}.${PROJECT
 set(CMAKE_C_STANDARD 17)
 set(CMAKE_C_STANDARD_REQUIRED ON)
 set(CMAKE_C_EXTENSIONS ON) # GNU extensions and POSIX standard
-set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_CXX_STANDARD 20)
 set(CMAKE_CXX_STANDARD_REQUIRED ON)
 set(CMAKE_CXX_EXTENSIONS ON)
 
@@ -71,6 +71,18 @@ if(MSVC)
 		set(CMAKE_C_STANDARD 90)
 		set(CMAKE_CXX_STANDARD 98)
 	endif()
+
+	if(MSVC_USE_MT)
+
+		set(CMAKE_MSVC_RUNTIME_LIBRARY "MultiThreaded$<$<CONFIG:Debug>:Debug>")
+	endif(MSVC_USE_MT)
+else(MSVC)
+
+	if(MSVC_USE_MT)
+
+		# this here just to absorb warning about not using `MSVC_USE_MT` (to
+		# enable **prepare_cmake.sh** to be simple)
+	endif(MSVC_USE_MT)
 endif(MSVC)
 
 
@@ -103,7 +115,7 @@ endif(Diagnosticism_OS_SIMULATE_WINDOWS_ON_UNIX)
 #
 # required:
 # - CLASP - required for testing;
-# - cstring;
+# - cstring - required for testing;
 # - STLSoft - required for testing;
 # - xTests - required for testing;
 #

include/diagnosticism/diagnosticism.h

@@ -4,7 +4,7 @@
  * Purpose: Main header file for Diagnosticm (C-API).
  *
  * Created: 23rd November 2024
- * Updated: 23rd January 2025
+ * Updated: 5th February 2025
  *
  * Home:    https://github.com/synesissoftware/Diagnosticism/
  *
@@ -50,8 +50,8 @@
 #ifndef DIAGNOSTICISM_DOCUMENTATION_SKIP_SECTION
 # define DIAGNOSTICISM_VER_DIAGNOSTICISM_H_DIAGNOSTICISM_MAJOR  0
 # define DIAGNOSTICISM_VER_DIAGNOSTICISM_H_DIAGNOSTICISM_MINOR  0
-# define DIAGNOSTICISM_VER_DIAGNOSTICISM_H_DIAGNOSTICISM_PATCH  1
-# define DIAGNOSTICISM_VER_DIAGNOSTICISM_H_DIAGNOSTICISM_EDIT   2
+# define DIAGNOSTICISM_VER_DIAGNOSTICISM_H_DIAGNOSTICISM_PATCH  2
+# define DIAGNOSTICISM_VER_DIAGNOSTICISM_H_DIAGNOSTICISM_EDIT   3
 #endif /* !DIAGNOSTICISM_DOCUMENTATION_SKIP_SECTION */
 
 
@@ -80,7 +80,7 @@
 #define DIAGNOSTICISM_VER_MAJOR         0
 #define DIAGNOSTICISM_VER_MINOR         0
 #define DIAGNOSTICISM_VER_PATCH         0
-#define DIAGNOSTICISM_VER_ALPHABETA     22
+#define DIAGNOSTICISM_VER_ALPHABETA     23
 
 #define DIAGNOSTICISM_VER \
     (0\

include/diagnosticism/doomgram.h

@@ -0,0 +1,141 @@
+
+#include <diagnosticism/diagnosticism.h>
+
+#include <stdbool.h>
+#include <stdint.h>
+#include <stdio.h>
+
+
+/* /////////////////////////////////////////////////////////////////////////
+ * API types
+ */
+
+/** T.B.C.
+ *
+ *
+ */
+struct diagnosticism_doomgram_t
+{
+    uint64_t    event_count;
+    uint64_t    total_event_time_ns;
+    uint64_t    min_event_time_ns;
+    uint64_t    max_event_time_ns;
+    uint64_t    oom_event_counts[12];
+    bool        has_overflowed;
+};
+#ifndef __cplusplus
+typedef struct diagnosticism_doomgram_t diagnosticism_doomgram_t;
+#endif
+
+#define DIAGNOSTICISM_DOOMGRAM_INITIALIZER                          \
+                                                                    \
+    {                                                               \
+        .event_count = 0,                                           \
+        .total_event_time_ns = 0,                                   \
+        .min_event_time_ns = 0,                                     \
+        .max_event_time_ns = 0,                                     \
+        .oom_event_counts = { 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0 },  \
+        .has_overflowed = 0,                                        \
+    }
+
+
+/* /////////////////////////////////////////////////////////////////////////
+ * API functions & macros
+ */
+
+/** Pushes an event with the given number of nanoseconds. */
+DIAGNOSTICISM_CALL(bool)
+diagnosticism_doomgram_push_event_time_ns(
+    diagnosticism_doomgram_t*   dg
+,   uint64_t                    time_in_ns
+);
+/** Pushes an event with the given number of microseconds. */
+DIAGNOSTICISM_CALL(bool)
+diagnosticism_doomgram_push_event_time_us(
+    diagnosticism_doomgram_t*   dg
+,   uint64_t                    time_in_us
+);
+/** Pushes an event with the given number of milliseconds. */
+DIAGNOSTICISM_CALL(bool)
+diagnosticism_doomgram_push_event_time_ms(
+    diagnosticism_doomgram_t*   dg
+,   uint64_t                    time_in_ms
+);
+/** Pushes an event with the given number of seconds. */
+DIAGNOSTICISM_CALL(bool)
+diagnosticism_doomgram_push_event_time_s(
+    diagnosticism_doomgram_t*   dg
+,   uint64_t                    time_in_s
+);
+
+
+#define diagnosticism_doomgram_num_events_in_1ns(pdg)       ((pdg)->oom_event_counts[ 0])
+#define diagnosticism_doomgram_num_events_in_10ns(pdg)      ((pdg)->oom_event_counts[ 1])
+#define diagnosticism_doomgram_num_events_in_100ns(pdg)     ((pdg)->oom_event_counts[ 2])
+#define diagnosticism_doomgram_num_events_in_1us(pdg)       ((pdg)->oom_event_counts[ 3])
+#define diagnosticism_doomgram_num_events_in_10us(pdg)      ((pdg)->oom_event_counts[ 4])
+#define diagnosticism_doomgram_num_events_in_100us(pdg)     ((pdg)->oom_event_counts[ 5])
+#define diagnosticism_doomgram_num_events_in_1ms(pdg)       ((pdg)->oom_event_counts[ 6])
+#define diagnosticism_doomgram_num_events_in_10ms(pdg)      ((pdg)->oom_event_counts[ 7])
+#define diagnosticism_doomgram_num_events_in_100ms(pdg)     ((pdg)->oom_event_counts[ 8])
+#define diagnosticism_doomgram_num_events_in_1s(pdg)        ((pdg)->oom_event_counts[ 9])
+#define diagnosticism_doomgram_num_events_in_10s(pdg)       ((pdg)->oom_event_counts[10])
+#define diagnosticism_doomgram_num_events_ge_100s(pdg)      ((pdg)->oom_event_counts[11])
+
+
+/**
+ *
+ * @pre NULL != dg
+ */
+DIAGNOSTICISM_CALL(bool)
+diagnosticism_doomgram_try_get_total_event_time_ns(
+    diagnosticism_doomgram_t*   dg
+,   uint64_t*                   value
+);
+
+#define diagnosticism_doomgram_try_get_total_event_time_ns_raw(pdg)         ((pdg)->total_event_time_ns)
+
+/**
+ *
+ * @pre NULL != dg
+ */
+DIAGNOSTICISM_CALL(bool)
+diagnosticism_doomgram_try_get_min_event_time_ns(
+    diagnosticism_doomgram_t*   dg
+,   uint64_t*                   value
+);
+
+/**
+ *
+ * @pre NULL != dg
+ */
+DIAGNOSTICISM_CALL(bool)
+diagnosticism_doomgram_try_get_max_event_time_ns(
+    diagnosticism_doomgram_t*   dg
+,   uint64_t*                   value
+);
+
+
+#ifndef DIAGNOSTICISM_DOCUMENTATION_SKIP_SECTION
+
+DIAGNOSTICISM_CALL(int)
+diagnosticism_doomgram_dump_to_stream(
+    FILE*                       stm
+,   diagnosticism_doomgram_t*   dg
+,   char const*                 var_name
+);
+#endif /* !DIAGNOSTICISM_DOCUMENTATION_SKIP_SECTION */
+
+
+DIAGNOSTICISM_CALL(char const*)
+diagnosticism_doomgram_to_strip_12(
+    diagnosticism_doomgram_t*   dg
+,   char                      (*ar)[12]
+);
+
+
+#pragma once
+
+
+/* ///////////////////////////// end of file //////////////////////////// */
+

src/CMakeLists.txt

@@ -5,7 +5,7 @@
 # Purpose:  CMake lists file for Diagnosticsm core library
 #
 # Created:  23rd November 2024
-# Updated:  23rd November 2024
+# Updated:  5th February 2025
 #
 # ######################################################################## #
 
@@ -47,6 +47,7 @@ set(TARGET_NAME core)
 
 set(CORE_SRCS
 	api.c
+	doomgram.c
 	tracing.c
 )
 
@@ -62,6 +63,7 @@ add_library(${TARGET_NAME}
 # `install()` step
 set(CORE_PUBLIC_HEADERS
 	"${CMAKE_SOURCE_DIR}/include/${PROJECT_NAME_LOWER}/${PROJECT_NAME_LOWER}.h"
+	"${CMAKE_SOURCE_DIR}/include/${PROJECT_NAME_LOWER}/doomgram.h"
 	"${CMAKE_SOURCE_DIR}/include/${PROJECT_NAME_LOWER}/tracing.h"
 )