Skip to content

Add non-spawning master and outstation task APIs#433

Merged
jadamcrain merged 14 commits into
mainfrom
feature/no-spawn
Jul 20, 2026
Merged

Add non-spawning master and outstation task APIs#433
jadamcrain merged 14 commits into
mainfrom
feature/no-spawn

Conversation

@jadamcrain

@jadamcrain jadamcrain commented Jul 19, 2026

Copy link
Copy Markdown
Member

Summary

  • add unstable non-spawning master builders for TCP, TLS, serial, and UDP
  • make association configuration scoped to its parent builder and return usable association and poll handles synchronously
  • defer configured poll and keep-alive timers until the master task is first polled
  • add unstable Server::into_task(listener) for TCP outstations with an already-bound listener
  • add a fail-fast serial typestate flow: SerialOutstation::newopenSerialOutstationTask::run
  • gate only the new 1.7.0 APIs behind unstable and document their semver exemption
  • compile and test the unstable feature in CI

Motivation

The existing spawning APIs choose where tasks run by calling tokio::spawn internally. These APIs let applications finish configuration and obtain concrete tasks or futures without spawning, so callers control the Tokio runtime and task set.

The type structure prevents associations from being attached to the wrong master and prevents a serial outstation task from existing until its port has opened successfully.

Existing stable APIs such as Server::bind_no_spawn and Server::add_outstation_no_spawn remain ungated. Stable examples continue to use the stable spawning API.

Behavior fixes

  • initially enabled TCP and serial sessions no longer emit a transient Disabled state
  • preconfigured poll and keep-alive periods begin when MasterTask::run is first polled rather than during configuration
  • TCP server handles and tracing use the supplied listener's actual local address

Validation

  • cargo test -p dnp3
  • cargo test --features unstable
  • stable and unstable Clippy with all targets and warnings denied
  • stable, unstable, and minimal feature builds
  • release build of dnp3, dnp3-ffi, and dnp3-ffi-java with minimal unstable features
  • unstable rustdoc
  • cargo fmt --all
  • git diff --check

closes #414

Adds MasterBuilder and UdpMasterBuilder types that separate protocol
configuration from transport binding and task execution. Callers control
which Tokio runtime or task set the master runs on instead of the library
calling tokio::spawn internally.

- MasterBuilder: stream transports (TCP, TLS, serial)
- UdpMasterBuilder: UDP transport with required SocketAddr per association
- Both produce a unified MasterTask with async fn run(self)
- Synchronous enable() and add_association() for pre-run configuration
- EndpointList::into_connect_handler() for easy ClientConnectionHandler creation
- Existing spawn_* functions unchanged (parallel API)
- Master example rewritten to use builder API
@jadamcrain
jadamcrain marked this pull request as ready for review July 20, 2026 17:42
Move the FFI TCP outstation server to the spawning add_outstation/bind
methods, driven via block_on to enter the runtime context, so the
library-defined dnp3-outstation-tcp and tcp-server spans are reused
instead of being lost. This restores 1.6.0 FFI logging behavior.

Document that the no-spawn APIs (add_outstation_no_spawn, bind_no_spawn)
and the new unstable MasterTask intentionally attach no span so callers
control instrumentation, and add a changelog note for the Rust-facing
behavior change.
Add a 1.7.0-RC3 changelog section documenting the non-spawning master
and outstation task APIs, the new EndpointList::into_connect_handler
helpers, and the no-spawn tracing span behavior change. Bump all crate
versions from 1.7.0-RC2 to 1.7.0-RC3.
The 1.7.0-RC3 version bump and changelog belong in a dedicated
"prepare 1.7.0-RC3" PR per RELEASE.md (using bump-version.sh, which also
updates the poms, csproj, CMakeLists, and sitedata.json). Revert them
here so this PR contains only the feature work and the FFI tracing-span
fix; the release prep will follow after this lands on main.
@jadamcrain
jadamcrain merged commit bf28467 into main Jul 20, 2026
33 checks passed
@jadamcrain
jadamcrain deleted the feature/no-spawn branch July 20, 2026 19:16
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Non-spawning API for master and outstation creation

1 participant