Enhance netutils and network modules for performance and stability

[mikecovlee]

This pull request introduces several improvements and behavioral changes to the network and netutils modules, focusing on more efficient wait strategies, configuration flexibility, and documentation updates. The most significant changes include the implementation of graduated waiting (spin-then-sleep) in fiber-based event loops, new CMake options to tune wait behavior, and updates to documentation and default parameters to reflect these changes.

Event loop and wait strategy improvements:

• Introduced a graduated wait mechanism in fiber environments: the system now performs a configurable number of fast spins (yield without sleep) before escalating to a short sleep, reducing CPU usage during idle periods. This is reflected in both the implementation and documentation (wait_impl, drain loops, and related fiber code). [1] [2] [3] [4] [5] [6] [7] [8] [9] [10] [11]

• All event loop worker fibers in netutils.csp now use fiber.sleep_for(IDLE_POLL_MS) instead of fiber.yield() when idle, further reducing unnecessary CPU usage. [1] [2] [3] [4]

Configuration and tuning:

• Added new CMake options NETWORK_WAIT_SLEEP_MS and NETWORK_FAST_SPIN_COUNT to control the sleep duration and spin count in the graduated wait logic. These are now passed as compile definitions and documented in the README. [1] [2] [3]

• Updated default values and parameters in netutils:

  • Reduced default worker_count from 64 to 32 for better resource usage.
  • Added constants IDLE_POLL_MS, FAST_POLL_MS, and ERROR_RECOVERY_MS for improved code clarity and maintainability.

Documentation and version updates:

• Updated documentation to describe the new graduated waiting behavior, configuration options, and clarifications on shutdown and recovery processes. [1] [2] [3] [4] [5] [6] [7] [8] [9]
• Changed version numbers to network 1.38.0_v6.6 and netutils 2.3 in all relevant files. [1] [2] [3] [4] [5] [6]

Minor code maintenance:

• Updated generated code in netutils.csp to use op_call instead of call for lambda structs, aligning with updated CovScript conventions. [1] [2] [3]
• Standardized log messages for safe_shutdown failures. [1] [2]

These changes collectively improve the efficiency, configurability, and clarity of the network stack and its documentation.

[Copilot]

Pull request overview

This PR updates the network C++ extension and the netutils CovScript module to reduce idle CPU usage and improve shutdown stability by introducing graduated waiting (spin-then-sleep), adding new build-time tuning knobs, and aligning documentation/versioning with the new behavior.

Changes:

• Implemented graduated waiting in network.cpp (yield for a bounded number of spins, then sleep_for) and applied similar wait/backpressure tweaks in netutils worker loops.
• Added new CMake/README configuration options (NETWORK_WAIT_SLEEP_MS, NETWORK_FAST_SPIN_COUNT) and updated related documentation.
• Updated package versions and regenerated compiled artifacts (.csp, .csym), plus minor maintenance adjustments.

Reviewed changes

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

Show a summary per file

File	Description
README.md	Updates versions and documents new CMake tuning options (and should document the new minimum SDK ABI requirement).
network.cpp	Adds graduated wait logic, introduces cs_runtime_sleep_for, and enforces a minimum CovScript SDK ABI version.
NETUTILS.md	Updates NetUtils protocol/docs for new worker behavior, shutdown semantics, and defaults.
netutils.ecs	Core behavioral changes to event loop, worker backpressure, shutdown re-entrancy handling, and new tuning constants.
netutils.csym	Regenerated bytecode module reflecting netutils.ecs changes.
netutils.csp	Regenerated compiled package reflecting netutils.ecs changes.
docs/async-architecture.md	Documents the new graduated waiting strategy and updated fiber wait behavior.
csbuild/network.json	Bumps network package version metadata.
csbuild/netutils.json	Bumps netutils package version metadata.
CNI_API.md	Updates API docs to reflect graduated wait behavior in safe_shutdown.
CMakeLists.txt	Adds new cache options and compile definitions for wait tuning.
argparse.csp	Regenerated artifact (timestamp-only change).

---

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