CNA-BUG-240: X11 header comments misdescribe the connection lifetime, the service accessors and the Xlib locking

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

X11Connection's comment says the connection opens on the first Video acquisition, but the platform opens it in its constructor; the accessor comments call services null before Video and AcquireSubsystem a thrower of PlatformNotSupportedException, neither of which holds; and the X11Platform class comment says every Xlib call goes through one per-instance mutex, when the backend's only mutex is the process-wide X error-policy mutex.

Identifier

CNA-BUG-240

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

Class and accessor documentation in CNA::Platform::X11::X11Platform and X11Connection (X11Platform.hpp, X11Display.hpp)

Expected behaviour

The header comments should describe the real connection lifetime and the real nullness and exception behaviour of the accessors, because they are how a maintainer reasons about when an X11 service is valid.

Actual behaviour at TARGET

X11Connection's comment says “The connection opens on the first Video acquisition and closes on the last release, matching the contract's refcounted subsystem rules.” In fact X11Platform::X11Platform calls OpenConnection in its constructor and ~X11Platform calls CloseConnection; AcquireSubsystem(Video) only throws when no connection exists and never opens one -- the comment on the constructor itself explains that connecting there is what makes the capability set stable for the instance's lifetime. The accessor comments in X11Platform.hpp say the keyboard, mouse, text-input, clipboard and Vulkan services are “null before Video”, but OpenConnection (run from the constructor) creates them, so they are non-null whenever the connection succeeded, regardless of any Video acquisition; and AcquireSubsystem's @throws PlatformNotSupportedException is never reached, because the implementation refcounts every subsystem and only ever throws PlatformException (Video with no connection).

Source locations

• modules/platform/src/X11/X11Display.hpp — X11Connection comment: opens on first Video acquisition, closes on last release
• modules/platform/src/X11/X11Platform.hpp — accessor comments 'null before Video'; AcquireSubsystem @throws PlatformNotSupportedException
• modules/platform/src/X11/X11Platform.cpp — constructor calls OpenConnection; destructor calls CloseConnection; AcquireSubsystem never opens the connection and throws only PlatformException
• modules/platform/src/X11/X11Error.cpp — PolicyMutex, the only mutex in the X11 backend

Evidence

Checked by reading the two headers and X11Platform.cpp's constructor, destructor, OpenConnection, AcquireSubsystem and the service accessors at 009d40f5. Not executed. The per-instance Xlib-mutex claim in the same X11Platform class comment is a separate defect already published by another package (see the note); it is not part of this entry.

Independently observed as a separate finding (merged): The X11Platform class comment says every Xlib call the backend makes goes through one per-instance mutex instead of XInitThreads(); no such mutex exists, the only one being the process-wide X error-policy mutex.

Independent re-verification: Checked by reading the two headers, X11Platform.cpp's constructor, destructor, OpenConnection, AcquireSubsystem and the service accessors, and by searching the X11 directory for mutexes, at 009d40f5. Not executed. The per-instance Xlib-mutex claim in the X11Platform class comment is part of this entry (merged from candidate P2-206); no other published entry covers it. The @throws PlatformNotSupportedException line mirrors IPlatform::AcquireSubsystem's own documentation, but no backend ever throws it from AcquireSubsystem, and OpenConnection's in-code comment repeats the 'valid exactly while Video is held' model.

Focused reproduction

No focused reproduction is known. Nothing has been invented here; the evidence above is what exists.

Current tests

The X11 suites acquire Video before using services, so the ordering the comments describe is never contradicted by a test; nothing asserts a service is null before Video or that AcquireSubsystem throws PlatformNotSupportedException.

Regression test

Correct the comments to say the connection and its services live from construction to destruction (when the connection succeeded), and remove the @throws PlatformNotSupportedException from AcquireSubsystem or make an unsupported subsystem actually throw it.

Blast radius

Maintainers reasoning about X11 service lifetime and subsystem acquisition from the header comments. No runtime effect.

Workaround

No workaround is known.