APIC Howto – How to Use APIC Utilities

← Back to Howto Index Full reference doc →

This guide shows how to use APIC's low-level utility functions for memory monitoring, string manipulation, file I/O, command-line parsing, and thread management in simulation, profiling, and real-time code.

1. Monitor memory health

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). Takes no arguments and returns nothing - call it as a bare statement, there is no status to check.
CheckHeapIntegrity() — Verifies heap consistency and checks for corruption or memory errors. Also takes no arguments and returns nothing.

Call ActivateMemoryMon() early in your program, then use CheckHeapIntegrity() at checkpoints to catch heap corruption before it causes a crash.

Global memory monitoring is process-wide - enable it from exactly one model's OnInit(), the same way OGIInit() is called from exactly one model. Calling ActivateMemoryMon() from more than one model is redundant and not an error, but there is no reason to do it.

2. Manipulate strings

Function	Purpose
`s2ws / ws2s`	Convert between `std::string` and `std::wstring`.
`ltrim / rtrim`	Remove leading or trailing characters (default null character).
`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`	Count occurrences of a specific character.
`str2num / str2dnum`	Convert strings to integer or double, with optional error reporting.

3. Parse command-line arguments

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

Use cmdOptionExists to guard optional flags, then call getCmdOption to read the associated value.

4. Work with files and directories

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.

5. Use array algorithms

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

6. Control threads

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

Function	Purpose
`EThreadPriority`	Enum of 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 runs a low-latency kernel and returns its version.

7. Put it together

// 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();