Skip to content

Replace collector shutdown booleans with explicit ShutdownMode semantics #1072

Description

@SoftFx

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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions