Problem
Recent shutdown hardening introduced a real semantic split:
- graceful
Stop() should preserve accepted work and perform bounded flush;
- terminal
Dispose() should clean up quickly under broken/nonresponsive transport and must not wait forever trying to deliver everything;
- start rollback may need cleanup semantics that are different from both.
Representing this with booleans such as flushAcceptedWork / preserveCanceledPackages is easy to misuse. The call sites do not explain the business meaning, and another boolean later would make the matrix harder to reason about.
Goal
Make shutdown behavior explicit and self-documenting with a small internal enum/model instead of boolean flags.
Proposed direction
Introduce an internal enum similar to:
internal enum ShutdownMode
{
GracefulStop,
TerminalDispose,
StartRollback
}
Then route stop behavior through this mode:
DataProcessor.StopAsync(ShutdownMode mode)
QueueProcessorBase.StopAsync(ShutdownMode mode)
Expected semantics:
GracefulStop
- preserve canceled in-flight packages;
- bounded flush accepted queued work;
- log leftovers after timeout.
TerminalDispose
- cancel/stop quickly;
- do not preserve nonresponsive in-flight transport work forever;
- still allow values produced by sensor stop/dispose, such as last-value flushes, to be drained with a bounded timeout where safe.
StartRollback
- cleanup after failed start without pretending the collector was fully running;
- should not leak background processors.
The exact behavior for StartRollback should be verified against existing tests before changing code.
Acceptance criteria
- No internal shutdown path passes raw booleans whose meaning is unclear.
DataCollector.Stop(), DataCollector.Stop(customStoppingTask), DataCollector.Dispose(), and start rollback all choose an explicit ShutdownMode.
- Tests document the mode split:
Stop() flushes accepted work;
Stop(customStoppingTask) flushes values produced by the custom task;
Dispose() finishes under nonresponsive transport;
- last-value sensor still flushes latest value on dispose.
- Full managed collector tests pass.
- Conformance and native CTest pass.
Notes
This should likely follow the queue-template refactor, or be done just before it, because both changes touch the same queue lifecycle surface.
Problem
Recent shutdown hardening introduced a real semantic split:
Stop()should preserve accepted work and perform bounded flush;Dispose()should clean up quickly under broken/nonresponsive transport and must not wait forever trying to deliver everything;Representing this with booleans such as
flushAcceptedWork/preserveCanceledPackagesis easy to misuse. The call sites do not explain the business meaning, and another boolean later would make the matrix harder to reason about.Goal
Make shutdown behavior explicit and self-documenting with a small internal enum/model instead of boolean flags.
Proposed direction
Introduce an internal enum similar to:
Then route stop behavior through this mode:
Expected semantics:
GracefulStopTerminalDisposeStartRollbackThe exact behavior for
StartRollbackshould be verified against existing tests before changing code.Acceptance criteria
DataCollector.Stop(),DataCollector.Stop(customStoppingTask),DataCollector.Dispose(), and start rollback all choose an explicitShutdownMode.Stop()flushes accepted work;Stop(customStoppingTask)flushes values produced by the custom task;Dispose()finishes under nonresponsive transport;Notes
This should likely follow the queue-template refactor, or be done just before it, because both changes touch the same queue lifecycle surface.