Item 82: Documente a thread safety

Importância de documentar a thread safety

• Parte do contrato da classe: A forma como uma classe lida com acesso concorrente é crucial para seus clientes.

Riscos de suposições erradas:

• Sincronização deficiente ou excessiva (Itens 78 e 79).
• Erros graves no comportamento do programa.

Problemas com o uso de synchronized como indicador

• Detalhe de implementação: Não é parte da API pública.
• Visão simplista: Thread safety não é uma propriedade binária (tudo ou nada); há níveis diferentes.

Níveis de thread safety
Imutável:

• Comportam-se como constantes.
• Não necessitam de sincronização externa.
• Exemplos: String, Long, BigInteger.

Incondicionalmente thread-safe:

• Instâncias mutáveis, mas com sincronização interna suficiente.
• Uso concorrente seguro sem sincronização adicional.
• Exemplos: AtomicLong, ConcurrentHashMap.

Condicionalmente thread-safe:

• Similar ao incondicional, mas alguns métodos requerem sincronização externa.
• Exemplo: Coleções de Collections.synchronized, que exigem sincronização ao iterar:

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

Sem thread safety:

• Necessário envolver métodos com sincronização externa.
• Exemplos: ArrayList, HashMap.

Hostil à thread:

• Não são seguras mesmo com sincronização externa.
• Geralmente resultado de erros, como modificação de dados estáticos sem sincronização.

Como documentar a thread safety
Documentação clara no Javadoc:

• Nível de segurança oferecido.
• Métodos ou sequências que requerem sincronização externa.
• Bloqueios específicos a serem usados.

Exemplo de documentação de sincronização para iteração:

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

Uso de objeto de bloqueio privado
Vantagens:

• Evita interferência de clientes e subclasses.
• Permite controle de concorrência mais sofisticado no futuro.

Exemplo:

private final Object lock = new Object();

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

Campos final: Protegem contra alterações acidentais no objeto de bloqueio.

Cuidados ao projetar classes para herança

• Usar o mesmo bloqueio em subclasse e classe base pode causar interferências.
• Preferir o bloqueio privado para evitar conflitos.

Resumo final

• Documente sempre a thread safety de uma classe (com texto ou anotações).
• Não confie apenas no modificador synchronized para documentar.
• Para classes incondicionalmente thread-safe, considere usar objetos de bloqueio privados.
• Classes condicionalmente thread-safe devem especificar quais bloqueios usar e quando.