Performance and Benchmarks
Relevant source files
The following files were used as context for generating this wiki page:
Performance and Benchmarks in FLEXT-Core represent a critical quality gate designed to ensure the framework maintains high execution efficiency, low memory overhead, and rapid startup times. This system focuses on quantifying the overhead of core components such as the dependency injection container, lazy import mechanisms, and runtime enforcement layers.
The project utilizes automated benchmarking tools and specific performance-oriented test suites to prevent regressions and maintain the "zero-debt baseline" required for enterprise-grade applications. These benchmarks are integrated into the broader quality gate infrastructure, which includes thresholds for complexity and resource consumption.
Sources: README.md:31, tests/benchmark/init.py
Benchmarking Architecture
The benchmarking infrastructure is organized into a dedicated suite within tests/benchmark/. It targets three primary pillars: memory footprint, execution speed of the DI container, and the efficiency of lazy-loading mechanisms.
The diagram above illustrates the logical separation of benchmark targets within the FLEXT-Core test suite.
Sources: tests/benchmark/init.py:1-26, tests/README.md:12-25
Dependency Injection Performance
The FlextContainer is subjected to performance tests to ensure that service registration and resolution do not become bottlenecks in complex application graphs. The benchmarks specifically measure the time taken for:
- Singleton Resolution: Speed of retrieving cached service instances.
- Factory Resolution: Overhead of instantiating new service objects on demand.
- Deep Dependency Resolution: Performance when resolving services with nested dependency trees.
Sources: tests/benchmark/test_container_performance.py, tests/benchmark/test_container_memory.py
Lazy Loading Efficiency
FLEXT-Core implements a custom lazy import system (flext_core.lazy) to minimize initial package load time. The benchmarks verify that:
- The
install_lazy_exportsandbuild_lazy_import_mapfunctions introduce negligible overhead. - Accessing a lazy attribute triggers the actual import exactly once with optimal throughput.
Sources: tests/benchmark/test_lazy_performance.py, tests/init.py:11-15
Performance Thresholds and Constraints
FLEXT-Core enforces strict architectural and code-level constraints via its enforcement data. These "code smells" are monitored because high complexity directly correlates with degraded runtime performance and maintainability.
Complexity Thresholds
The project defines maximum allowable values for various code metrics to ensure the engine remains performant.
| Metric | Threshold | Fix Strategy |
|---|---|---|
| Function Parameters | 5 | Decompose or use domain context object |
| Return Statements | 5 | Refactor to single result path |
| Nesting Depth | 4 | Extract helper functions to flatten flow |
| Function Complexity (Cyclomatic) | 14 | Decompose into smaller helpers |
| File Complexity (Cyclomatic) | 49 | Split module into focused units |
Sources: src/flext_core/_constants/_enforcement_data/smells.json:2-9, 19-48
Resource Invariants
System constants define hard limits for operational parameters, ensuring predictable performance under load.
- Timeouts:
MIN_TIMEOUT_SECONDSmust be greater than 0, whileDEFAULT_TIMEOUT_SECONDSis constrained between MIN and MAX values. - Pagination:
MAX_PAGE_SIZEis enforced to prevent excessive memory consumption during query operations. - Retries: Backoff strategies and retry counts are limited to prevent resource exhaustion during failure loops.
Sources: tests/unit/test_constants_new.py:23-44
Execution and Quality Gates
Benchmarks are executed as part of the canonical make verbs. The project utilizes pytest-benchmark to collect metrics and compare them against historical baselines.
This sequence shows how performance and complexity checks are integrated into the developer workflow.
Sources: CONTRIBUTING.md:32-42, pyproject.toml:116, README.md:31-34
Tools and Dependencies
The performance monitoring system relies on several key libraries defined in the project configuration:
- pytest-benchmark: Primary engine for executing timed benchmarks.
- radon: Used for measuring cyclomatic complexity and maintainability indices.
- vulture: Detects dead code that could otherwise bloat the runtime footprint.
- beartype: Used for high-performance runtime type checking with O(1) complexity.
Sources: pyproject.toml:98, 116, 127, 246, tests/unit/test_beartype_engine.py
Conclusion
Performance in FLEXT-Core is not treated as an afterthought but as a structural requirement. By combining lazy-loading patterns, strict complexity thresholds (e.g., max cyclomatic complexity of 14 per function), and automated container benchmarks, the framework ensures it remains suitable for enterprise environments where efficiency and predictable resource usage are paramount.