[Effective Java] 스레드 안전성 수준을 문서화하라

💥 개요

한 메서드를 여러 스레드가 동시에 호출할 때 그 메서드가 어떻게 동작하느냐는 해당 클래스와 이를 사용하는 클라이언트 사이의 중요한 계약과 같다. 아무 언급도 없으면 가정을 해야하고, 그 가정이 틀리면 동기화를 충분히 못하거나 지나치게한 상태일 것이며, 두 가지 심각한 오류로 이어질 수 있다.

 

⚠️ 자바독 기본 옵션 생성 API 문서는 synchronized가 포함되지 않는다.

메서드 선언에 synchronized 한정자를 선언할지는 구현 이슈일 뿐 API에 속하지 않는다.

멀티 스레드 환경에서도 API를 안전하게 사용하게 하려면 클래스가 지원하는 스레드 안전성 수준을 정확히 명시해야 한다. 일반적인 경우 스레드 안전성이 높은 순서는 아래와 같다.

1. 불변(immutable) : 이 클래스의 인스턴스는 마치 상수와 같아 외부 동기화도 필요없다. (String, Long, BigInteger)
2. 무조건적 스레드 안전(unconditionally thread-safe): 이 클래스의 인스턴스는 수정될 수 있으나, 내부에서 충실히 동기화하여 별도의 외부 동기화 없이 동시에 사용해도 안전하다. (AtomicLong ,ConcurrentHashMap)
3. 조건부 스레드 안전(conditionally thread-safe): 무조건적 스레드 안전과 같으나, 일부 메서드는 동시에 사용하려면 외부 동기화가 필요하다. (Collections.synchronized 래퍼 메서드가 반환한 컬렉션들)
4. 스레드 안전하지 않음(not thread-safe): 이 클래스의 인스턴스는 수정될 수 있다. 동시에 사용하려면 각각의 메서드 호출을 클라이언트가 선택한 외부 동기화 메커니즘으로 감싸야한다. (ArrayList , HashMap)
5. 스레드 적대적(thread-hostil): 이 클래스는 모든 메서드 호출을 외부 동기화로 감싸더라도 멀티스레드 환경에서 안전하지 않다. 문제를 고쳐 재배포하거나 사용자제 (deprecated) API로 지정한다.

 

Conditionally Thread-safe의 문서화

• 어떤 순서로 호출할 때 외부 동기화가 필요한지 검토해야한다.
• 그 순서로 호출하려면 어떤 락 혹은 락들을 얻어야 하는지 알려줘야 한다.

synchronizedMap이 반환한 맵의 컬렉션 뷰를 순회하려면 반드시 그 맵을 락으로 사용해 수동으로 동기화하라.

• 클래스의 스레드 안전성은 보통 클래스의 문서화 주석에 기재하지만 독특한 특성의 메서드라면 메서드의 주석에 기재하도록 한다.
• 반환타입만으로 명확히 알 수 없는 정적 팩터리라면 반환 객체의 스레드 안전성을 반드시 문서화 해야한다. 

 

😀 클래스의 Lock 제공

• 클래스가 외부에 사용이 가능한 락을 제공하는 경우 클라이언트에서 일련의  메서드 호출을 원자적으로 수행이 가능하다.
• 유연성에는 대가가 따른다. 내부에서 처리하는 고성능 동시성 메커니즘과 혼용할 수 없다. (ConcurrentHashMap과 같은 동시성 컬렉션과 함께 사용 X)
• 클라이언트가 락을 오래 쥐고 놓지 않는 서비스 거부 공격을 수행할 수 있다. 
• 서비스 거부 공격을 막으려면 synchronized(공개락과 마찬가지) 메서드 대신  비공개 락 객체를 사용해야한다.
• 락 필드는 항상 final로 선언하라
• 비공개 락 객체 관용구는 무조건적 스레드 안전 클래스에서만 사용할 수 있다.

// 비공개 락 객체, final 선언! : 락 객체 교체 상황 방지를 위함
private final Object lock = new Object();

public void someMethod() {
  synchronized(lock) {
    ...
  }
}

 

모든 클래스가 자신의 스레드 안전성 정보를 명확히 문서화해야 한다.
정확한 언어로 명확히 설명하거나 스레드 안전성 어노테이션을 사용할 수 있다.
synchronized 한정자는 문서화와 관련이 없다.
조건부 스레드 안전 클래스는 메서드를 어떤 순서로 호출할 때 외부 동기화가 요구되고, 그때 어떤 락을 얻어야 하는지도 알려줘야 한다.
무조건적 스레드 안전 클래스를 작성할 때는 synchronized 메서드가 아닌 비공개 락 객체를 사용하자.
이렇게 해야 클라이언트나 하위 클래스에서 동기화 메커니즘을 깨드리는 걸 예방할 수 있고, 필요하다면 다음에 더 정교한 동시성을 제어 메커니즘으로 재구현할 여지가 생긴다.