CNA-BUG-241: docs/devices-event-contract.md and docs/devices-thread-safety.md describe sensor behaviour the code no longer has

CNA snapshot 009d40f5  ·  Known Issues › Current bugs  ·  source links pinned to 009d40f5

The event contract says the Android bridge swallows handler exceptions silently, and the thread-safety document misnames the counter guard for two sensors and calls same-instance Start/Dispose safe while its known-gap section says otherwise.

Identifier

CNA-BUG-241

Category

Bug

Subsystem

Documentation & release tooling

Status

Open

Verified against

CNA 009d40f5 (009d40f5dd085c4e674d3479675fac84b12b3e0a)

Severity

Low (a triage suggestion, not a project priority)

Evidence basis

Source-verified: read at TARGET, not executed

Tests touching this area

Yes: see Current tests

Affected contract

docs/devices-event-contract.md section 6 (exception semantics) and docs/devices-thread-safety.md (per-class guarantees and the known gap)

Expected behaviour

CNA's devices maintainer documents describe what the code does; the internals pages, the devices workflow and future fixes cite them.

Actual behaviour at TARGET

1. docs/devices-event-contract.md section 6, headed "decided but not yet uniformly implemented", says the callback_(sample) site in AndroidSensorBridge::Run is wrapped in a bare catch (...) { } "with no logging and no test-visible counter at all" and leaves the fix to DEVPERF-005. At TARGET, AndroidSensorBridge.cpp catches std::exception and everything else and records a NativeDiagnosticRecord through NativeDiagnosticSink::Record, citing DEVPERF-005, and nine NativeDiagnosticSinkTest cases pin the sink.
2. docs/devices-thread-safety.md says instance construction and destruction never corrupt the shared counter, "guarded by a static instanceCountMutex_". Only Compass and Motion have that mutex; Accelerometer and Gyroscope guard their counter with PlatformSensorSubsystem<TSensor>::mutex_. The guarantee holds; the named mechanism is wrong for two classes.
3. The same document says Accelerometer/Gyroscope Start()/Stop()/Dispose() "are safe to call concurrently with each other, on the same or different instances", while its "Known gap" section says a Dispose() racing Start() on the same instance is unsupported for all four classes, with the read-unlock-Stop() shape present in Accelerometer.cpp and Gyroscope.cpp.

Source locations

• docs/devices-event-contract.md — section 6 describes the Android bridge as silent
• docs/devices-thread-safety.md — instanceCountMutex_ attribution; same-instance safety claim versus the Known gap section
• modules/devices/src/Sensors/Detail/AndroidSensorBridge.cpp — AndroidSensorBridge::Run routes handler exceptions to NativeDiagnosticSink::Record
• modules/devices/tests/Microsoft/Devices/Sensors/Detail/NativeDiagnosticTests.cpp — NativeDiagnosticSinkTest cases
• modules/devices/src/Sensors/Accelerometer.cpp — constructor and Dispose(bool) guard instanceCount_ with the subsystem mutex; Dispose reads started_ and then calls Stop
• modules/devices/src/Sensors/Compass.cpp — the static instanceCountMutex_ exists only in Compass and Motion

Evidence

Checked by reading the two documents and the sensor sources and tests named above at 009d40f5; not executed. In each contradiction the code is the correct side, and nothing marks the documents as describing a future state. The devices internals page already flags the first two points.

Focused reproduction

# Shown for reference: the stale statements next to the code.
grep -n "bare" docs/devices-event-contract.md
grep -n "NativeDiagnosticSink::Record" modules/devices/src/Sensors/Detail/AndroidSensorBridge.cpp
grep -rn "instanceCountMutex_" modules/devices/src/Sensors/
grep -n "same or different instances" docs/devices-thread-safety.md

Current tests

NativeDiagnosticTests.cpp pins the sink; nothing checks the documents against the code.

Regression test

Rewrite section 6 to state the uniform NativeDiagnosticSink policy and its debug-only log line; name PlatformSensorSubsystem::mutex_ for Accelerometer/Gyroscope; restrict the first bullet to what the known-gap section allows.

Blast radius

Maintainers and reviewers who trust the documents: someone following section 6 may re-implement diagnostics that exist or treat the Android path as silent, and the thread-safety bullet invites concurrent Dispose/Start on one instance. No runtime behaviour changes.

Workaround

Trust the code and the devices internals page over these two documents.