fix: harden MultiprocessingWriter shutdown and error handling

[bednar]

Closes #230

Proposed Changes

Harden MultiprocessingWriter lifecycle and worker error handling:

• Replace assertion-based runtime state validation with explicit exceptions.
• Guarantee queue task completion on successful and failed writes.
• Add idempotent close() with bounded worker shutdown and configurable close_timeout.
• Ensure shutdown callbacks run at most once.
• Add regression coverage for timeout, write failure, poison-pill shutdown, callback failures, and lifecycle validation.
• Document the change in CHANGELOG.md.

Checklist

• CHANGELOG.md updated
• Rebased/mergeable (blocked while integration CI is pending)
• A test has been added if appropriate
• Tests pass locally
• Commit messages are conventional
• Sign CLA (if not already signed)

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 86.19%. Comparing base (d2fc4da) to head (948ea36).

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #241      +/-   ##
==========================================
- Coverage   87.43%   86.19%   -1.25%     
==========================================
  Files          28       28              
  Lines        2030     2072      +42     
==========================================
+ Hits         1775     1786      +11     
- Misses        255      286      +31     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Copilot]

🟡 Changes recommended

The new unit tests hard-code start_method="fork" and assert fork, which is non-portable (e.g., Windows) and inconsistent with the library default and existing integration coverage expecting spawn.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

This PR hardens MultiprocessingWriter’s lifecycle management and worker-loop error handling to avoid inconsistent shutdown states and JoinableQueue.join() deadlocks, while adding regression tests and documenting the behavior change.

Changes:

• Replaces assertion-based state checks with explicit RuntimeErrors and adds an idempotent close() with bounded shutdown (close_timeout) plus best-effort __del__ cleanup.
• Ensures queue.task_done() is always called for dequeued items (including write failures), and makes on_shutdown run at most once.
• Adds regression tests for lifecycle validation, worker timeout, poison-pill shutdown, and callback/write failures; documents the change in the changelog.

File summaries

File	Description
influxdb_client_3/write_client/client/util/multiprocessing_helper.py	Implements the hardened shutdown lifecycle, deterministic worker cleanup behavior, and callback/error handling improvements.
tests/test_multiprocessing_helper.py	Adds unit/regression coverage for the updated lifecycle and worker behavior (with a portability concern noted in comments).
CHANGELOG.md	Documents the MultiprocessingWriter shutdown/error-handling hardening.

Review details

Suppressed comments (1)

tests/test_multiprocessing_helper.py:121

• This assertion is tied to the test helper's hard-coded fork start method; if the helper is updated to use the library default (spawn) for portability, this expectation should be updated accordingly.

def test_get_start_processing_method_returns_context_method():
    assert make_writer().get_start_processing_method() == "fork"

• Files reviewed: 3/3 changed files
• Comments generated: 1
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

🔵 Needs a closer look

The new unit test test_get_start_processing_method_returns_context_method asserts "fork" despite constructing the writer with start_method="spawn", which will cause test failures.

Review details

Suppressed comments (1)

tests/test_multiprocessing_helper.py:122

• This test expects the start method to be "fork", but make_writer() explicitly constructs MultiprocessingWriter(start_method="spawn", ...), so get_start_processing_method() should return "spawn". As written, the test will fail (and also disagrees with existing integration tests that expect "spawn" by default).

def test_get_start_processing_method_returns_context_method():
    assert make_writer().get_start_processing_method() == "fork"

• Files reviewed: 3/3 changed files
• Comments generated: 0 new
• Review effort level: Lite