feat(lambda-rs): Add policy to control the event loops control-flow

[vmarcella]

Summary

Add an opt-in, configurable winit event loop control-flow policy so apps that don’t need continuous rendering (tools/editors) can avoid ControlFlow::Poll and reduce CPU/power usage when idle.

Related Issues

• Resolves [Feature] Add configurable event loop control flow policy to reduce CPU usage when idle #98

Changes

• Add EventLoopPolicy (Poll, Wait, WaitUntil { target_fps }) to the winit wrapper and implement Loop::run_forever_with_policy(...).
• Add ApplicationRuntimeBuilder::with_event_loop_policy(...) (defaults to Poll for backwards compatibility) and wire it into ApplicationRuntime execution.
• Re-export EventLoopPolicy from lambda::runtimes for easy consumption.
• Update docs + minimal example to demonstrate EventLoopPolicy::Wait for event-driven apps.
• Fix nightly clippy never_loop lint failure by removing an unnecessary return inside an iterator adapter closure.

Type of Change

• Bug fix (non-breaking change that fixes an issue)
• Feature (non-breaking change that adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation (updates to docs, specs, tutorials, or comments)
• Refactor (code change that neither fixes a bug nor adds a feature)
• Performance (change that improves performance)
• Test (adding or updating tests)
• Build/CI (changes to build process or CI configuration)

Affected Crates

• lambda-rs
• lambda-rs-platform
• lambda-rs-args
• lambda-rs-logging
• Other:

Checklist

• Code follows the repository style guidelines (cargo +nightly fmt --all)
• Code passes clippy (cargo clippy --workspace --all-targets -- -D warnings)
• Tests pass (cargo test --workspace)
• New code includes appropriate documentation
• Public API changes are documented
• Breaking changes are noted in this PR description

Testing

Commands run:

cargo +nightly fmt --all
rustup run nightly cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace

Manual verification steps (if applicable):

1. (Optional) Run an example app and verify CPU usage drops when idle with EventLoopPolicy::Wait.

Screenshots/Recordings

N/A

Platform Testing

• macOS
• Windows
• Linux

Additional Notes

• Default remains Poll to avoid behavior changes for existing applications unless they opt in.
• WaitUntil is best-effort wakeup scheduling (control-flow only), not frame pacing/vsync.

[github-actions]

✅ Coverage Report

📊 View Full HTML Report (download artifact)

Overall Coverage

Metric	Value
Total Line Coverage	76.26%
Lines Covered	10270 / 13467

Changed Files in This PR

File	Coverage	Lines
crates/lambda-rs-platform/src/winit/mod.rs	5.96%	9/151
crates/lambda-rs/examples/minimal.rs	N/A	(no coverage data)
crates/lambda-rs/src/render/mod.rs	78.79%	1137/1443
crates/lambda-rs/src/runtimes/application.rs	25.17%	113/449
crates/lambda-rs/src/runtimes/mod.rs	N/A	(no coverage data)

PR Files Coverage: 61.62% (1259/2043 lines)

---

Generated by cargo-llvm-cov · Latest main coverage

_{Last updated: 2026-02-10 21:37:11 UTC · Commit: ae80c45}

[Copilot]

Pull request overview

Adds an opt-in winit event loop control-flow policy to Lambda runtimes so applications can avoid continuous polling and reduce CPU/power usage when idle, while preserving Poll as the default for backward compatibility.

Changes:

• Introduces EventLoopPolicy (Poll, Wait, WaitUntil { target_fps }) and Loop::run_forever_with_policy(...) in the platform winit wrapper.
• Wires policy through ApplicationRuntimeBuilder::with_event_loop_policy(...) into ApplicationRuntime execution.
• Updates public exports and docs/examples to demonstrate EventLoopPolicy::Wait, and fixes a clippy never_loop lint.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
crates/lambda-rs/src/runtimes/mod.rs	Re-exports EventLoopPolicy for easier consumption from lambda::runtimes.
crates/lambda-rs/src/runtimes/application.rs	Adds policy to the runtime builder and uses it when running the event loop.
crates/lambda-rs/src/render/mod.rs	Removes an unnecessary return to satisfy clippy linting.
crates/lambda-rs/examples/minimal.rs	Demonstrates configuring the runtime with EventLoopPolicy::Wait.
crates/lambda-rs/README.md	Updates getting-started snippet to include and recommend EventLoopPolicy::Wait for event-driven apps.
crates/lambda-rs-platform/src/winit/mod.rs	Implements EventLoopPolicy and run_forever_with_policy mapping to winit ControlFlow.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.