Skip to content

TROUBLESHOOTING.md

Latest commit

 

History

History
369 lines (250 loc) · 6.75 KB

TROUBLESHOOTING.md

File metadata and controls

369 lines (250 loc) · 6.75 KB
Raw
doc_id THR-GUID-024
doc_title Troubleshooting Guide
doc_version 1.0.0
doc_date 2026-04-04
doc_status Released
project thread_system
category GUID

Troubleshooting Guide

SSOT: This document is the single source of truth for Troubleshooting Guide.

Language: English | 한국어

This guide covers common issues and their solutions when working with Thread System.

Table of Contents

  1. Build Issues
  2. Runtime Issues
  3. Performance Issues
  4. Platform-Specific Issues
  5. Getting Help

Build Issues

C++20 Compilation Errors

Symptom: Build fails with errors related to C++20 features like std::format, std::jthread, or concepts.

Solution:

  1. Check your compiler version:
g++ --version      # Should be 11+
clang++ --version  # Should be 14+
  1. Ensure C++20 is enabled:
cmake -S . -B build -DCMAKE_CXX_STANDARD=20
  1. If using older compilers, disable unsupported features:
cmake -S . -B build \
    -DDISABLE_STD_FORMAT=ON \
    -DDISABLE_STD_JTHREAD=ON

vcpkg Installation Fails

Symptom: dependency.sh or dependency.bat fails to install vcpkg or packages.

Solution:

  1. Clean and reinstall:
rm -rf vcpkg
./scripts/dependency.sh
  1. Manual installation:
git clone https://github.com/Microsoft/vcpkg.git
./vcpkg/bootstrap-vcpkg.sh
export VCPKG_ROOT=$PWD/vcpkg
  1. Check network connectivity and proxy settings.

CMake Cannot Find Compiler

Symptom: CMake fails with "No CMAKE_CXX_COMPILER could be found."

Solution:

  1. Set compiler explicitly:
export CC=/usr/bin/gcc
export CXX=/usr/bin/g++
cmake -S . -B build
  1. Or use CMake variables:
cmake -S . -B build \
    -DCMAKE_C_COMPILER=/usr/bin/gcc \
    -DCMAKE_CXX_COMPILER=/usr/bin/g++

Link Errors on Windows

Symptom: Unresolved external symbols or LNK errors on Windows.

Solution:

  1. Ensure consistent runtime library:
cmake -S . -B build -DCMAKE_MSVC_RUNTIME_LIBRARY=MultiThreadedDLL

  1. Use matching Debug/Release configurations.

  2. Check that all dependencies are built with the same settings.

Tests Fail to Build

Symptom: Google Test related build errors.

Solution:

  1. Install Google Test via vcpkg:
./vcpkg/vcpkg install gtest
  1. Or disable tests:
cmake -S . -B build -DBUILD_TESTING=OFF

Runtime Issues

Thread Pool Doesn't Start

Symptom: Jobs are not being processed.

Solution:

  1. Ensure workers are added before starting:
auto pool = std::make_shared<thread_pool>("MyPool");

// Add workers first
std::vector<std::unique_ptr<thread_worker>> workers;
workers.push_back(std::make_unique<thread_worker>());
pool->enqueue_batch(std::move(workers));

// Then start
pool->start();
  1. Check that start() is called.

Deadlock or Hang

Symptom: Application hangs during job execution.

Solution:

  1. Avoid submitting jobs that wait for other jobs from the same pool:
// BAD: Potential deadlock
pool->submit_task([&pool]() {
    auto future = pool->submit_task([]() { /* inner job */ });
    future.get();  // Deadlock if all workers are busy
});

  1. Use separate pools for nested job submissions.

  2. Run with ThreadSanitizer to detect issues:

cmake -S . -B build -DENABLE_TSAN=ON

Memory Leaks

Symptom: Memory usage grows over time.

Solution:

  1. Ensure proper shutdown:
pool->shutdown_pool(false);  // Wait for completion
  1. Run with AddressSanitizer:
cmake -S . -B build -DENABLE_ASAN=ON
./build/bin/your_app
  1. Check that all jobs are completing and not stuck.

Unexpected Job Failures

Symptom: Jobs fail silently or return unexpected errors.

Solution:

  1. Check job return values:
pool->execute(std::make_unique<callback_job>([]() -> kcenon::common::VoidResult {
    // Your work
    return kcenon::common::ok();
}));
  1. Use proper error handling:
auto result = pool->execute(std::move(job));
if (result.has_error()) {
    std::cerr << "Job failed: " << result.get_error().message() << "\n";
}

Performance Issues

Low Throughput

Symptom: Jobs are processed slower than expected.

Solution:

  1. Match worker count to workload:
// For CPU-bound work
size_t workers = std::thread::hardware_concurrency();

// For I/O-bound work
size_t workers = std::thread::hardware_concurrency() * 2;
  1. Use lock-free queue for high contention:
thread_module::adaptive_job_queue q{
    thread_module::adaptive_job_queue::queue_strategy::LOCKFREE
};
  1. Profile your application to identify bottlenecks.

High CPU Usage When Idle

Symptom: CPU usage is high even with no jobs.

Solution:

  1. Use blocking wait instead of busy polling:
// Configure worker with proper idle behavior
// Workers should use condition variables for waiting
  1. Check that shutdown is called when pool is no longer needed.

Lock Contention

Symptom: Poor scaling with multiple threads.

Solution:

  1. Use adaptive or lock-free queues:
thread_module::adaptive_job_queue q{
    thread_module::adaptive_job_queue::queue_strategy::ADAPTIVE
};

  1. Reduce shared state in jobs.

  2. Batch related operations to reduce queue operations.

Platform-Specific Issues

macOS: Tests Disabled in CI

Symptom: Tests are skipped on macOS CI environments.

Explanation: Tests are disabled by default on macOS due to CI environment limitations. Run tests locally:

cd build && ctest --verbose

Windows: Character Encoding Issues

Symptom: Console output shows garbled text.

Solution:

  1. Use UTF-8 encoding:
#ifdef _WIN32
SetConsoleOutputCP(CP_UTF8);
#endif
  1. libiconv is excluded on Windows by default.

Linux: Permission Issues

Symptom: Cannot execute scripts or binaries.

Solution:

  1. Make scripts executable:
chmod +x scripts/*.sh
chmod +x build/bin/*

Getting Help

Debug Information

When reporting issues, include:

  1. System information:
uname -a           # OS info
g++ --version      # Compiler version
cmake --version    # CMake version
  1. Build configuration:
cmake -S . -B build -L  # List CMake variables
  1. Error messages: Full error output from the build or runtime.

Resources

Last Updated: 2025-12-10