Overview

Date: 2026-05-11

Time: 15:42

Overview

This is a benchmark and demonstration script that compares FTL2's in-process Python module system against traditional subprocess-based execution (as used by Ansible). It measures timing for file operations, command execution, the async executor API, and batch vs sequential execution, showing that FTL modules achieve ~250x+ speedup by eliminating subprocess overhead. It also serves as a usage-pattern reference for the four main ways to invoke FTL modules.

Usage Patterns

The script demonstrates four invocation styles, from lowest-level to highest:

1. Direct synchronous call:

from ftl2.ftl_modules import ftl_file, ftl_command
result = ftl_file(path='/tmp/test', state='touch')  # returns dict with 'changed' key
result = ftl_command(cmd='echo hello')

2. Async execute() with auto module selection:

from ftl2.ftl_modules import execute
result = await execute('file', {'path': '/tmp/test', 'state': 'touch'})
# result.success, result.used_ftl

3. Convenience run() function (kwargs instead of dict):

from ftl2.ftl_modules import run
result = await run('command', cmd='echo hello')
# result.output['stdout']

4. Concurrent multi-host execution:

from ftl2.ftl_modules import execute_on_hosts, LocalHost
hosts = [LocalHost(name=f'host{i}') for i in range(3)]
results = await execute_on_hosts(hosts, 'command', {'cmd': 'echo ok'})

5. Batch execution (concurrent tasks):

from ftl2.ftl_modules import execute_batch
tasks = [('command', {'cmd': 'true'}, None) for _ in range(10)]
await execute_batch(tasks)

API and Configuration

• ftl_file(path, state, ...) — synchronous file module; accepts Ansible-style parameters like state='touch'
• ftl_command(cmd) — synchronous command module; wraps subprocess
• execute(modulename, paramsdict) — async executor; returns result with .success and .used_ftl attributes
• run(module_name, kwargs)** — async convenience wrapper around execute(); params as kwargs
• executebatch(tasks) — async concurrent execution; tasks are (module, params, hostor_none) tuples
• executeonhosts(hosts, module, params) — async concurrent execution across host objects
• LocalHost(name=...) — creates a local host target for executeonhosts

No config files or environment variables. The script adds src/ to sys.path for development imports.

Key Behaviors

• In-process execution: FTL modules (ftlfile, ftlcommand) run as Python functions, not subprocesses — the core performance win over Ansible's model.
• Overhead vs raw Python: ftl_file adds measurable but small overhead over Path.touch() due to validation, mode handling, and result formatting.
• Batch speedup: execute_batch provides near-linear speedup over sequential execute() calls by running tasks concurrently via asyncio.
• Result shapes differ: Direct ftl* calls return plain dicts (e.g., {'changed': True}). execute()/run() return result objects with .success, .usedftl, .output attributes.
• Benchmarks use 50 iterations by default (10 for batch tests), reporting mean, stddev, min, max in milliseconds.

Relationships

• Imports from ftl2.ftlmodules: ftlfile, ftlcommand, execute, run, executebatch, executeonhosts, LocalHost — this is the primary user-facing module API.
• Target repo: Lives under examples/ in the faster-than-light2 repository.
• References: Points to benchmarks/RESULTS.md for detailed benchmark data.
• Module naming: Uses short names ('file', 'command') with execute()/run(), mapping to the ftlfile/ftlcommand functions internally.