Item Documente a thread safety

Importance of documenting thread safety

• Part of the class contract: How a class handles concurrent access is crucial to its clients.

Risks of wrong assumptions:

• Poor or excessive synchronization (Items 78 and 79).
• Serious errors in the program's behavior.

Problems with using synchronized as an indicator

• Implementation detail: Not part of the public API.
• Simplistic view: Thread safety is not a binary property (all or nothing); there are different levels.

Thread safety levels
Immutable:

• They behave like constants.
• No external synchronization required.
• Examples: String, Long, BigInteger.

Unconditionally thread-safe:

• Mutable instances, but with sufficient internal synchronization.
• Secure concurrent use without additional synchronization.
• Examples: AtomicLong, ConcurrentHashMap.

Conditionally thread-safe:

• Similar to unconditional, but some methods require external synchronization.
• Example: Collections.synchronized, which require synchronization when iterating:

Map<String, String> syncMap = Collections.synchronizedMap(new HashMap<>());
synchronized (syncMap) {
    for (String key : syncMap.keySet()) {
        // Iteração segura
    }
}

No thread safety:

• Need to involve methods with external synchronization.
• Examples: ArrayList, HashMap.

Hostile to thread:

• They are not secure even with external synchronization.
• Usually the result of errors, such as modifying static data without synchronization.

How to document thread safety
Clear documentation in Javadoc:

• Level of security offered.
• Methods or sequences that require external synchronization.
• Specific locks to use.

Example synchronization documentation for iteration:

/**
 * É necessário sincronizar manualmente ao iterar sobre as views deste mapa.
 * Exemplo:
 * synchronized (map) {
 *     for (Object key : map.keySet()) {
 *         // Iteração segura
 *     }
 * }
 */

Use of private lock object
Advantages:

• Avoids interference from clients and subclasses.
• Allows more sophisticated concurrency control in the future.

Example:

private final Object lock = new Object();

public void threadSafeMethod() {
    synchronized (lock) {
        // Código protegido
    }
}

Final fields: Protect against accidental changes to the lock object.

Care when designing classes for inheritance

• Using the same lock in subclass and base class may cause interference.
• Prefer private lock to avoid conflicts.

Final summary

• Always document the thread safety of a class (with text or notes).
• Don't just rely on the synchronized modifier to document.
• For unconditionally thread-safe classes, consider using private locking objects.
• Conditionally thread-safe classes must specify which locks to use and when.

The above is the detailed content of Item Documente a thread safety. For more information, please follow other related articles on the PHP Chinese website!