src: clamp idle_diff before computing proc_diff

[santigimeno]

Avoid unsigned underflow when loop_diff is slightly larger than idle_diff due to clock skew on idle loops.

Fixes: https://github.com/nodesource/nsolid-private/issues/15

Summary by CodeRabbit

• Bug Fixes
  • Corrected event loop utilization reporting on certain platforms to prevent negative or inflated values.
  • Ensures idle and loop time metrics remain consistent and non-negative, improving accuracy of utilization stats.
  • Reduces spurious spikes in reported usage, leading to more reliable monitoring data.

[coderabbitai]

Walkthrough

Introduces a guard in get_event_loop_stats_ to clamp idle_diff to not exceed loop_diff, preventing unsigned underflow and ensuring non-negative proc_diff and stable loop utilization calculations. No other logic or structural changes.

Changes

Cohort / File(s)	Summary of changes
Event loop stats underflow guard src/nsolid/nsolid_api.cc	Clamp idle_diff to loop_diff before computing utilization metrics to avoid unsigned underflow and invalid values; no other logic modified.

Sequence Diagram(s)

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Suggested reviewers

• juanarbol
• RafaelGSS

Poem

A nibble of math in a warren of C,
I tightened the bounds so bytes hop free.
No underflow burrows, no runaway spin—
Loop-time carrots now measure within.
Thump-thump goes the queue, calm as can be,
Utilization true—hare-approved, happily. 🥕

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title Check	✅ Passed	The title succinctly describes the primary change by indicating that idle_diff is clamped before proc_diff is calculated, which directly reflects the added guard logic without extraneous details or file lists. It is concise, clear, and focused on the core functionality updated by the pull request.
Linked Issues Check	✅ Passed	The pull request adds a clamp to idle_diff so it cannot exceed loop_diff, preventing unsigned underflow and thus avoiding the negative or excessively large loopUtilization and loopIdlePercent values described in issue #15. This directly fulfills the coding objective of correcting invalid loop-related metrics on Windows without introducing unrelated changes.
Out of Scope Changes Check	✅ Passed	The changeset only adds a guard to clamp idle_diff in get_event_loop_stats_ and does not modify any other logic paths or files, ensuring all modifications are directly related to fixing the underflow issue. No functionality outside of loop metric computation has been altered.

✨ Finishing touches

• 📝 Generate Docstrings

🧪 Generate unit tests

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch santi/clamp_loop_delay

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 987f908 and 13eb35c.

📒 Files selected for processing (1)

• src/nsolid/nsolid_api.cc (1 hunks)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (6)

• GitHub Check: lint-js-and-md
• GitHub Check: test-macOS
• GitHub Check: build-tarball
• GitHub Check: coverage-windows
• GitHub Check: test-linux (ubuntu-24.04)
• GitHub Check: test-linux (ubuntu-24.04-arm)

🔇 Additional comments (1)

src/nsolid/nsolid_api.cc (1)

2165-2170: Clamp idle_diff to loop_diff avoids underflow.

Saturating idle_diff when the idle clock nudges past loop_diff keeps proc_diff non-negative and eliminates the runaway loop utilization numbers we were seeing on Windows under heavy idle periods. Clean and targeted fix.

Tip

👮 Agentic pre-merge checks are now available in preview!

Pro plan users can now enable pre-merge checks in their settings to enforce checklists before merging PRs.

• Built-in checks – Quickly apply ready-made checks to enforce title conventions, require pull request descriptions that follow templates, validate linked issues for compliance, and more.
• Custom agentic checks – Define your own rules using CodeRabbit’s advanced agentic capabilities to enforce organization-specific policies and workflows. For example, you can instruct CodeRabbit’s agent to verify that API documentation is updated whenever API schema files are modified in a PR. Note: Upto 5 custom checks are currently allowed during the preview period. Pricing for this feature will be announced in a few weeks.

Please see the documentation for more information.

Example:

reviews:
  pre_merge_checks:
    custom_checks:
      - name: "Undocumented Breaking Changes"
        mode: "warning"
        instructions: |
          Pass/fail criteria: All breaking changes to public APIs, CLI flags, environment variables, configuration keys, database schemas, or HTTP/GraphQL endpoints must be documented in the "Breaking Change" section of the PR description and in CHANGELOG.md. Exclude purely internal or private changes (e.g., code not exported from package entry points or explicitly marked as internal).

Please share your feedback with us on this Discord post.

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[juanarbol]

SGTM