Java Reference
In-Depth Information
// ...
}
Documenting Thread-Confinement Policies
DeanSutherlandandWilliamScherlisproposeannotationsthatcandocumentthread-con-
finement policies. Theirapproachallowsverification oftheannotations against as-written
code [Sutherland 2010].
For example, the following annotations express the design intent that a program has,
at most, one Abstract Window Toolkit (AWT) event dispatch thread and several com-
pute threads, andthat the compute threads are forbidden tohandle AWT data structures or
events:
@ThreadRole AWT, Compute
@IncompatibleThreadRoles AWT, Compute
@MaxRoleCount AWT 1
Documenting Wait-Notify Protocols
According to Goetz and colleagues [Goetz 2006],
A state-dependent class should either fully expose (and document) its waiting and
notification protocols to subclasses, or prevent subclasses from participating in them
at all. (This is an extension of “design and document for inheritance, or else prohibit
it” [EJ Item 15].) At the very least, designing a state-dependent class for inheritance
requiresexposingtheconditionqueuesandlocksanddocumentingtheconditionpre-
dicates and synchronization policy; it may also require exposing the underlying state
variables. (The worst thing a state-dependent class can do is expose its state to sub-
classesbutnotdocumentitsprotocolsforwaitingandnotification; thisislikeaclass
exposing its state variables but not documenting its invariants.) (p. 395)
Wait-notify protocols should be documented adequately. Currently, we are not aware
of any annotations for this purpose.
Applicability
Annotatingconcurrentcodehelpsdocumentthedesignintentandcanbeusedtoautomate
the detection and prevention of race conditions and data races.
