Architecture

Developer-focused reference for the LoliProfiler codebase. Covers data flow, components, patterns, and pitfalls for contributors.

Core Data Flow

GUI Mode:

1. Android agent hooks malloc/free and sends RawStackInfo records via TCP
2. MainWindow receives records in real-time, builds StackTraceModel
3. User interacts with visualizations (timeline, tree map, call tree, fragmentation)
4. Data can be saved to .loli files for later analysis

CLI Mode:

1. Android agent hooks malloc/free and sends RawStackInfo records via TCP
2. CliProfiler receives records and caches to disk (cache/ directory)
3. After capture completes (duration timeout or Ctrl+C), processes cached records
4. Saves complete .loli file for GUI analysis

Key Components

Entry Points:

• src/main.cpp — GUI mode entry point (Qt Widgets application)
• src/main_cli.cpp — CLI mode entry point (QCoreApplication, no GUI)

Controllers:

• MainWindow (src/mainwindow.cpp) — GUI controller, manages all UI and profiling operations
• CliProfiler (src/cliprofiler.cpp) — CLI controller, manages headless profiling workflow
• ProfileComparator (src/profilecomparator.cpp) — Comparison engine for detecting memory regressions between two .loli files

Process Management (Base: AdbProcess):

• StartAppProcess — Launches target application via ADB
• StackTraceProcess — TCP socket connection to Android profiling agent, receives allocation/deallocation records
• MemInfoProcess — Captures system memory info (/proc/meminfo) via ADB
• ScreenshotProcess — Takes device screenshots for correlation
• AddressProcess — Resolves memory addresses to function symbols

Data Models:

• StackTraceModel — Table model containing StackRecord entries (UUID, time, size, address, library)
• StackTraceProxyModel — Filtering/sorting proxy for stack traces
• RawStackInfo — Raw allocation/deallocation record format from Android agent
• SMapsSection — Memory mapping information from /proc/pid/smaps

Android Native Libraries (plugins/Android/):

• Built with NDK for multiple architectures (armeabi, armeabi-v7a, arm64-v8a)
• Hooks malloc/calloc/realloc/free using custom interception techniques
• Communicates with desktop client via TCP socket on port 44515
• Sends stack traces with allocation/deallocation metadata

Key Data Structures

StackRecord:

struct StackRecord {
    QUuid uuid_;        // Call stack UUID
    quint32 seq_;       // Sequence number
    qint32 time_;       // Timestamp
    qint32 size_;       // Allocation size
    quint64 addr_;      // Memory address
    quint64 funcAddr_;  // Function address
    HashString library_; // Library name (optimized string storage)
};

RawStackInfo (from Android agent):

• Contains allocation/deallocation flag, timestamp, size, address, call stack frames

Call Stack Maps:

• callStackMap_ — Maps UUIDs to call stack sequences (library + function address pairs)
• symbloMap_ — Address-to-symbol resolution cache
• freeAddrMap_ — Tracks deallocated addresses to filter out freed memory

Conditional Compilation

The codebase uses the NO_GUI_MODE preprocessor flag to enable CLI-only builds:

• When defined, excludes Qt Widgets/Charts/OpenGL dependencies
• Allows shared components like ConfigDialog to function as data containers without UI
• Process classes (StartAppProcess, ScreenshotProcess) work in both modes
• Build system automatically defines this flag when compiling LoliProfilerCLI

When adding features to shared components:

1. Guard GUI-specific code with #ifndef NO_GUI_MODE
2. Ensure core functionality works without Qt Widgets dependencies
3. Test both executables after changes
4. Update CMakeLists.txt if adding new files

Configuration Sharing

Both GUI and CLI modes share the same configuration file:

• Windows: %LOCALAPPDATA%\MoreFun\LoliProfiler\loli3.conf
• macOS/Linux: ~/.local/share/MoreFun/LoliProfiler/loli3.conf

Both executables set organization name ("MoreFun") and application name ("LoliProfiler") to ensure config compatibility. This allows CLI to use settings configured in GUI (compiler type, architecture, whitelist, blacklist).

Android Agent Protocol

The Android agent communicates via TCP socket with binary protocol:

• Port: 44515 (forwarded via ADB)
• Commands: START_CAPTURE, STOP_CAPTURE, SMAPS_DUMP
• Data format: LZ4-compressed RawStackInfo records

Multi-threading

• GUI operations run on main Qt thread
• ADB processes run asynchronously (QProcess)
• TCP socket communication is event-driven
• Data processing may use Qt::Concurrent for heavy operations
• CLI mode uses QCoreApplication (no GUI event loop)

Signal Handling (CLI Mode)

CLI implements graceful shutdown via SIGINT/SIGTERM handlers:

• Signal handler is async-signal-safe (uses write() instead of stdio)
• Invokes CliProfiler::RequestStop() via Qt::QueuedConnection (thread-safe)
• Ensures proper SMAPS dump and file save before exit
• Allows profiling across app restarts (doesn't auto-exit when app exits)

Comparison Algorithm

ProfileComparator compares two .loli files in five steps:

1. Load both profiles and build allocation maps
2. Group allocations by (library_name, function_address) key
3. Calculate statistics (new, removed, changed allocations)
4. Build call tree with size/count deltas
5. Export as text or .loli format

File Format

.loli files use a binary format:

• Magic number: 0xA4B3C2D1
• Version: 106
• Contains: stack records, call stacks, symbols, memory info series, screenshots, SMAPS sections

Common Pitfalls

1. Path spaces on Windows — Always quote paths with spaces when passing to ADB commands
2. JDWP injection — Requires debuggable apps or rooted devices
3. Symbol file structure — Must match Android library directory layout
4. Memory optimization — Use streaming mode for large datasets (CLI enables by default)
5. Comparison version mismatch — Both .loli files must have the same version/magic number