APIC – Utility Functions & System Helpers guide

Utility Functions & System Helpers

This section covers low-level utility functions for memory monitoring, string manipulation, file I/O, command-line argument parsing, and thread management. These utilities are widely used across simulation, profiling, and real-time systems.

Memory Utilities

• ActivateMemoryMon() – Monitors memory allocation and deallocation during runtime. The goal is performance, not just leak detection: allocation and deallocation cause real-time performance issues, so this catches them happening where they shouldn't (e.g. inside a model's hot path).
• CheckHeapIntegrity() – Verifies heap consistency and checks for corruption or memory errors.

String Utilities

Comprehensive functions for string trimming, splitting, case conversion, and prefix/suffix checks.

• s2ws / ws2s – Convert between std::string and std::wstring.
• ltrim / rtrim – Remove leading or trailing characters (default null character) from strings.
• split – Split a string into a std::vector<std::string> using a delimiter.
• startsWith / endsWith – Check if a string starts or ends with a given prefix/suffix.
• replaceAll – Replace all occurrences of a substring in a string.
• makeLower / makeUpper – Convert strings or char arrays to lower/upper case.
• strStartWith – Case-insensitive prefix check.
• CountCharInString – Counts occurrences of a specific character.
• str2num / str2dnum – Convert strings to integer or double with optional error reporting.

Command-Line Argument Utilities

• getCmdOption – Retrieves a command-line argument value.
• cmdOptionExists – Checks if a command-line option exists.

The application stores its raw argv[] in SystemConfig.arguments at startup. Read any name="value" argument from it in a model's OnInit():

// Usage: projectApp.exe myArg="value"
std::string myArgValue;
getCmdOption(SystemConfig.arguments, "myArg", myArgValue);

// Boolean-style flag, e.g. projectApp.exe ?
if (cmdOptionExists(SystemConfig.arguments, "?"))
{
    // print usage/help and exit
}

File & Directory Utilities

• DirectoryExists – Checks if a given directory path exists.
• GetWorkingDirectory – Returns the current working directory.
• WriteToFile / ReadFromFile – Write or read raw byte buffers to/from files.
• GetFileSize / ReadFile – Get file size or read file contents into a buffer.
• GetFiles – Retrieve file names from a directory matching an optional pattern.

Algorithms

• gcd_of_array – Returns the greatest common divisor of integers in an array.

Threading Utilities

These functions allow explicit control over thread priority and CPU affinity, useful in high-performance and low-latency applications.

• EThreadPriority – Enum defining thread priority levels: Undef, Lowest, BelowNormal, Normal, AboveNormal, Highest, RealTime.
• SetThreadPriority / SetCurrentThreadPriority – Set priority for a specific thread or the current thread.
• SetThreadAffinity / SetCurrentThreadAffinity – Pin threads to specific CPU cores.
• SetRealtimePriority – Set a thread to real-time priority on specified cores.
• GetThreadPriority / GetCurrentThreadPriority – Retrieve the priority of a thread or the current thread.
• GetThreadAffinity / GetCurrentThreadAffinity – Get CPU core affinity of a thread or the current thread.
• GetNumberOfCores – Returns the number of CPU cores available.
• IsLowLatencyKernel – Checks if the system is running a low-latency kernel and returns its version.

Frame-Gating Utilities

CSimEngine::CMinorFrameGate – Guards a piece of code so it executes at most once per CoreEngine minor frame, regardless of how many times or from how many call sites it's invoked during that frame (e.g. a shared helper called from several stream triggers, or a function reachable from multiple code paths). Declare a static gate instance local to the code being guarded, and check ShouldRun() before proceeding.

static CSimEngine::CMinorFrameGate frameGate;
if (!frameGate.ShouldRun())
    return;

// ... code here runs at most once per minor frame ...

CSimEngine::CValueChangeGate – Guards a piece of code so it only runs when a specific element's value has actually changed since the last check, skipping redundant processing when nothing changed:

static CSimEngine::CValueChangeGate valueChangeGate(&pLRU->block.element);
if (!valueChangeGate.ShouldRun())
    return;

// ... code here runs only when pLRU->block.element changed since the last call ...

Usage Examples

// Memory monitoring
ActivateMemoryMon();
CheckHeapIntegrity();

// File utilities
if (DirectoryExists("C:/Data")) {
    auto files = GetFiles("C:/Data", ".txt");
}

// String operations
std::string name = "SimulationFile.TXT";
if (endsWith(name, ".TXT")) {
    makeLower(name); // "simulationfile.txt"
}

// Thread utilities
std::thread t([](){ /* do work */ });
SetThreadPriority(&t, EThreadPriority::RealTime);
SetThreadAffinity(&t, std::vector{true, false, false, true});
t.join();