# workers URL: /api/utils/workers/ Section: utils -------------------------------------------------------------------------------- workers - Kida window.BENGAL_THEME_DEFAULTS = { appearance: 'light', palette: 'brown-bengal' }; window.Bengal = window.Bengal || {}; window.Bengal.enhanceBaseUrl = '/kida/assets/js/enhancements'; window.Bengal.watchDom = true; window.Bengal.debug = false; window.Bengal.enhanceUrls = { 'toc': '/kida/assets/js/enhancements/toc.632a9783.js', 'docs-nav': '/kida/assets/js/enhancements/docs-nav.57e4b129.js', 'tabs': '/kida/assets/js/enhancements/tabs.aac9e817.js', 'lightbox': '/kida/assets/js/enhancements/lightbox.1ca22aa1.js', 'interactive': '/kida/assets/js/enhancements/interactive.fc077855.js', 'mobile-nav': '/kida/assets/js/enhancements/mobile-nav.d991657f.js', 'action-bar': '/kida/assets/js/enhancements/action-bar.d62417f4.js', 'copy-link': '/kida/assets/js/enhancements/copy-link.7d9a5c29.js', 'data-table': '/kida/assets/js/enhancements/data-table.1f5bc1eb.js', 'lazy-loaders': '/kida/assets/js/enhancements/lazy-loaders.a5c38245.js', 'holo': '/kida/assets/js/enhancements/holo.ee13c841.js', 'link-previews': '/kida/assets/js/enhancements/link-previews.8d906535.js' }; (function () { try { var defaults = window.BENGAL_THEME_DEFAULTS || { appearance: 'system', palette: '' }; var defaultAppearance = defaults.appearance; if (defaultAppearance === 'system') { defaultAppearance = (window.matchMedia && window.matchMedia('(prefers-color-scheme: dark)').matches) ? 'dark' : 'light'; } var storedTheme = localStorage.getItem('bengal-theme'); var storedPalette = localStorage.getItem('bengal-palette'); var theme = storedTheme ? (storedTheme === 'system' ? defaultAppearance : storedTheme) : defaultAppearance; var palette = storedPalette ?? defaults.palette; document.documentElement.setAttribute('data-theme', theme); if (palette) { document.documentElement.setAttribute('data-palette', palette); } } catch (e) { document.documentElement.setAttribute('data-theme', 'light'); } })(); { "prerender": [ { "where": { "and": [ { "href_matches": "/docs/*" }, { "not": { "selector_matches": "[data-external], [target=_blank], .external" } } ] }, "eagerness": "conservative" } ], "prefetch": [ { "where": { "and": [ { "href_matches": "/*" }, { "not": { "selector_matches": "[data-external], [target=_blank], .external" } } ] }, "eagerness": "conservative" } ] } Skip to main content Magnifying Glass ESC Recent Clear Magnifying Glass No results for "" Start typing to search... ↑↓ Navigate ↵ Open ESC Close Powered by Lunr )彡 DocumentationInfoAboutArrow ClockwiseGet StartedCodeSyntaxTerminalUsageNoteTutorialsStarburstExtendingBookmarkReferenceTroubleshootingReleasesDevGitHubKida API Reference Magnifying Glass Search ⌘K Palette Appearance Chevron Down Mode Monitor System Sun Light Moon Dark Palette Snow Lynx Brown Bengal Silver Bengal Charcoal Bengal Blue Bengal List )彡 Magnifying Glass Search X Close Documentation Caret Down Info About Arrow Clockwise Get Started Code Syntax Terminal Usage Note Tutorials Starburst Extending Bookmark Reference Troubleshooting Releases Dev Caret Down GitHub Kida API Reference Palette Appearance Chevron Down Mode Monitor System Sun Light Moon Dark Palette Snow Lynx Brown Bengal Silver Bengal Charcoal Bengal Blue Bengal Kida API Reference Caret Right Analysis analyzer cache config dependencies landmarks metadata purity roles Caret Right Compiler Caret Right Statements basic control_flow functions special_blocks template_structure variables _protocols coalescing core expressions utils Caret Right Environment core exceptions filters loaders protocols registry tests Caret Right Parser Caret Right Blocks control_flow core functions special_blocks template_structure variables _protocols core errors expressions statements tokens Caret Right Utils html lru_cache workers _types bytecode_cache kida lexer nodes template tstring Kida API ReferenceUtils ᗢ Caret Down Link Copy URL External Open LLM text Copy Copy LLM text Share with AI Ask Claude Ask ChatGPT Ask Gemini Ask Copilot Module utils.workers Worker pool auto-tuning utilities for free-threaded Python. Provides workload-aware worker count calculation for ThreadPoolExecutor usage. Calibrated for Python 3.14t (free-threading) where CPU-bound template rendering can achieve true parallelism without GIL contention. Key Features: Environment detection (CI vs local vs production) Free-threading detection (GIL status) Workload type profiles calibrated for no-GIL execution Template complexity estimation for optimal scheduling Example: >>> from kida.utils.workers import get_optimal_workers, should_parallelize >>> contexts = [{"name": f"User {i}"} for i in range(100)] >>> if should_parallelize(len(contexts)): ... workers = get_optimal_workers(len(contexts)) ... with ThreadPoolExecutor(max_workers=workers) as executor: ... results = list(executor.map(template.render, contexts)) Note: Profiles are calibrated for free-threaded Python (3.14t+). On GIL-enabled Python, CPU-bound parallelism is limited. 3Classes7Functions Classes WorkloadType 3 ▼ Workload characteristics for auto-tuning. On free-threaded Python, CPU-bound work can now parallel… Workload characteristics for auto-tuning. On free-threaded Python, CPU-bound work can now parallelize effectively. This changes optimal worker counts compared to GIL-enabled Python. Attributes Name Type Description RENDER — Template rendering (CPU-bound, string operations). Primary workload for Kida. Benefits significantly from free-threading. COMPILE — Template compilation/parsing (CPU-bound, AST operations). Moderate parallelism benefit due to shared cache access. IO_BOUND — File loading, network operations. Can use more workers as threads wait on I/O. Environment 3 ▼ Execution environment for tuning profiles. Execution environment for tuning profiles. Attributes Name Type Description CI — Constrained CI runner (typically 2-4 vCPU). Use minimal workers to avoid resource contention. LOCAL — Developer machine (typically 8-16 cores). Use moderate workers for good performance. PRODUCTION — Server deployment (16+ cores). Can use more workers for high throughput. WorkloadProfile 5 ▼ Tuning profile for a workload type. Tuning profile for a workload type. Attributes Name Type Description parallel_threshold int Minimum tasks before parallelizing. Below this, thread overhead exceeds benefit. min_workers int Floor for worker count. max_workers int Ceiling for worker count. cpu_fraction float Fraction of cores to use (0.0-1.0). free_threading_multiplier float Extra scaling when GIL is disabled. Functions is_free_threading_enabled 0 bool ▼ Check if Python is running with the GIL disabled. def is_free_threading_enabled() -> bool Returns bool detect_environment 0 Environment ▼ Auto-detect execution environment for tuning. **Detection order:** 1. Explicit… def detect_environment() -> Environment Auto-detect execution environment for tuning. Detection order: Explicit KIDA_ENV environment variable CI environment variables (GitHub Actions, GitLab CI, etc.) Default to LOCAL Returns Environment get_optimal_workers 1 int ▼ Calculate optimal worker count based on workload characteristics. Auto-scales … def get_optimal_workers(task_count: int) -> int Calculate optimal worker count based on workload characteristics. Auto-scales based on: Workload type (render vs compile vs I/O) Environment (CI vs local vs production) Free-threading status (GIL enabled/disabled) Available CPU cores (fraction based on workload) Task count (no point having more workers than tasks) Optional task weight for heavy/light work estimation Parameters Name Type Description task_count int Number of tasks to process (e.g., contexts to render) Returns int should_parallelize 1 bool ▼ Determine if parallelization is worthwhile for this workload. Thread pool over… def should_parallelize(task_count: int) -> bool Determine if parallelization is worthwhile for this workload. Thread pool overhead (~1-2ms per task) only pays off above threshold. This function helps avoid the overhead for small workloads. Parameters Name Type Description task_count int Number of tasks to process Returns bool estimate_template_weight 1 float ▼ Estimate relative complexity of a template for worker scheduling. Heavy templa… def estimate_template_weight(template: Template) -> float Estimate relative complexity of a template for worker scheduling. Heavy templates (many blocks, macros, filters) get higher weights, causing them to be scheduled earlier to avoid straggler effect. Weight factors: Source size: +0.5 per 5KB above 5KB threshold Block count: +0.1 per block above 3 Macro count: +0.2 per macro Inheritance: +0.5 if extends another template Parameters Name Type Description template Template Template instance to estimate Returns float order_by_complexity 1 list[Template] ▼ Order templates by estimated complexity for optimal worker utilization. Schedu… def order_by_complexity(templates: list[Template]) -> list[Template] Order templates by estimated complexity for optimal worker utilization. Scheduling heavy templates first reduces the "straggler effect" where one slow render delays overall completion. Parameters Name Type Description templates list[Template] List of templates to order Returns list[Template] get_profile 2 WorkloadProfile ▼ Get the workload profile for inspection or testing. def get_profile(workload_type: WorkloadType, environment: Environment | None = None) -> WorkloadProfile Parameters Name Type Description workload_type WorkloadType Type of work environment Environment | None Execution environment (auto-detected if None) Default: None Returns WorkloadProfile ← Previous utils List © 2026 Kida built in ᓚᘏᗢ { "linkPreviews": { "enabled": true, "hoverDelay": 200, "hideDelay": 150, "showSection": true, "showReadingTime": true, "showWordCount": true, "showDate": true, "showTags": true, "maxTags": 3, "includeSelectors": [".prose"], "excludeSelectors": ["nav", ".toc", ".breadcrumb", ".pagination", ".card", "[class*='-card']", ".tab-nav", "[class*='-widget']", ".child-items", ".content-tiles"], "allowedHosts": [], "allowedSchemes": ["https"], "hostFailureThreshold": 3 } } window.BENGAL_LAZY_ASSETS = { tabulator: '/kida/assets/js/tabulator.min.js', dataTable: '/kida/assets/js/data-table.js', mermaidToolbar: '/kida/assets/js/mermaid-toolbar.9de5abba.js', mermaidTheme: '/kida/assets/js/mermaid-theme.344822c5.js', graphMinimap: '/kida/assets/js/graph-minimap.ff04e939.js', graphContextual: '/kida/assets/js/graph-contextual.355458ba.js' }; window.BENGAL_ICONS = { close: '/kida/assets/icons/close.911d4fe1.svg', enlarge: '/kida/assets/icons/enlarge.652035e5.svg', copy: '/kida/assets/icons/copy.3d56e945.svg', 'download-svg': '/kida/assets/icons/download.04f07e1b.svg', 'download-png': '/kida/assets/icons/image.c34dfd40.svg', 'zoom-in': '/kida/assets/icons/zoom-in.237b4a83.svg', 'zoom-out': '/kida/assets/icons/zoom-out.38857c77.svg', reset: '/kida/assets/icons/reset.d26dba29.svg' }; Arrow Up -------------------------------------------------------------------------------- Metadata: - Word Count: 1205 - Reading Time: 6 minutes