|
| 1 | +--- |
| 2 | +title: Configuration |
| 3 | +description: Configuration settings for the Error System policy |
| 4 | +tags: |
| 5 | + - c++ |
| 6 | + - errors |
| 7 | + - configuration |
| 8 | +--- |
| 9 | + |
| 10 | +[`error_config.hpp`](https://github.com/GraphicalPlayground/gp-engine/blob/main/src/runtime/core/public/errors/error_config.hpp) |
| 11 | + |
| 12 | +# Error Configuration |
| 13 | + |
| 14 | +The `gp::error::config` struct is the central policy hub for the **Graphical Playground** error system. It defines how the engine behaves when an error occurs-determining whether to capture a call stack, |
| 15 | +trigger a debugger breakpoint, deduplicate recurring logs, or shut down the process. |
| 16 | + |
| 17 | +## Configuration Categories |
| 18 | + |
| 19 | +The configuration is divided into specialized sub-structs to manage different aspects of the error-handling pipeline. |
| 20 | + |
| 21 | +### 1. Stacktrace Settings (`stacktrace_s`) |
| 22 | + |
| 23 | +Controls the expensive operation of walking the call stack. |
| 24 | +- `capture_from`: The minimum severity required to trigger a stack capture. |
| 25 | +- `max_frames`: Limits the depth of the trace to balance detail vs. performance. |
| 26 | +- `skip_frames`: Number of frames to ignore from the top of the stack. This is typically used to hide the internal error-reporting functions so the trace starts exactly where the error was triggered. |
| 27 | +- `enabled`: Master toggle. Usually disabled in Shipping builds to reclaim CPU cycles. |
| 28 | + |
| 29 | +### 2. Breakpoint Settings (`breakpoint_s`) |
| 30 | + |
| 31 | +Manages interaction with native debuggers (Visual Studio, GDB, LLDB). |
| 32 | +- `break_from`: Severity threshold to trigger a hardware breakpoint. |
| 33 | +- `check_is_debugged`: If true, the engine checks if a debugger is actually attached before breaking. This prevents the "Capture Instance" from hanging or crashing in automated environments like CI/CD. |
| 34 | + |
| 35 | +### 3. Abort Settings (`abort_s`) |
| 36 | + |
| 37 | +Defines the "Point of No Return." |
| 38 | +- `abort_from`: Severity threshold that forces a process exit. |
| 39 | +- `use_terminate`: If true, calls `std::terminate()` (which can trigger cleanup) instead of the immediate `std::abort()`. |
| 40 | +- `flush_before_abort`: Ensures all active log sinks (like files or consoles) write their remaining buffers to disk before the process dies. |
| 41 | + |
| 42 | +### 4. Filter Settings (`filter_s`) |
| 43 | + |
| 44 | +The first line of defense against performance degradation and log spam. |
| 45 | +- `global_min_severity`: Any record below this level is discarded immediately. |
| 46 | +- `de_duplicate`: If enabled, the system tracks identical errors (same message, code, and thread). If the same error occurs multiple times within the `de_duplicate_window_ms`, only the first instance is recorded. |
| 47 | + |
| 48 | +## Environment Presets |
| 49 | + |
| 50 | +The system provides four static factory methods to quickly initialize the engine based on the current build target. |
| 51 | + |
| 52 | +| Preset | Purpose | Key Behavior | |
| 53 | +|-----------------|------------------|--------------------------------------------------------------------------| |
| 54 | +| development() | Active coding | Verbose tracing, breaks on Errors, captures everything. | |
| 55 | +| qa() | Staging/Testing | No debug breaks, deduplication enabled, moderate filtering. | |
| 56 | +| shipping() | Final Product | Minimal overhead, stacktraces disabled, global minimum set to Warning. | |
| 57 | +| test() | Unit Testing | Silent console, captures only Fatal/Critical to avoid test spam. | |
| 58 | + |
| 59 | +### Usage Example |
| 60 | + |
| 61 | +```cpp |
| 62 | +// Initialize the error system with the Shipping policy |
| 63 | +gp::error::config my_config = gp::error::config::shipping(); |
| 64 | + |
| 65 | +// Manually override a specific setting if needed |
| 66 | +my_config.filter.de_duplicate = false; |
| 67 | + |
| 68 | +gp::error::system::initialize(my_config); |
| 69 | +``` |
| 70 | +
|
| 71 | +## Key Performance Considerations |
| 72 | +
|
| 73 | +1. **Deduplication**: In a high-end engine, a failing system in a 144Hz render loop could generate thousands of logs per second. Enabling `de_duplicate` is critical to prevent the disk I/O from stalling the main thread. |
| 74 | +2. **Stacktrace Overhead**: Capturing a stack trace is a heavy kernel-level operation. Use `stacktrace.capture_from` wisely; capturing traces for `severity::info` or `severity::trace` will significantly degrade frame rates. |
| 75 | +3. **Global Minimum**: Use `global_min_severity` to strip out development-only "Trace" messages in release builds, ensuring the CPU doesn't waste time formatting strings that will never be seen. |
0 commit comments