Skip to content

Document ApplicationManager lock ordering and thread-safety contract #448

Description

@sfloess

Part of #423: Race condition potential in ApplicationManager concurrent operations

Problem

Lock ordering and thread-safety invariants are not documented, making it easy for future contributors to introduce deadlocks or race conditions during maintenance.

Tasks

  • Add class-level Javadoc documenting the lock ordering hierarchy
  • Document which methods are thread-safe and which require external synchronization
  • Document the thread-safety contract for listener callbacks (which thread, ordering guarantees)
  • Add @ThreadSafe / @GuardedBy annotations where appropriate (javax.annotation.concurrent)
  • Add a THREADING.md or section in the module README explaining the concurrency model

Acceptance Criteria

  • A developer new to the codebase can understand the locking strategy from documentation alone
  • Lock ordering is explicitly stated and matches the implementation
  • Thread-safety annotations are present on all shared mutable state

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions