아이템 82. 스레드 안전성 수준을 문서화하라

[coalong]

아이템 소개

멀티스레드 환경에서도 API 를 안전하게 사용하려면 스레드 안전성을 API 문서에 명시해야 한다.
이는 클라이언트의 지나치거나 부족한 동기화를 사용하는 것을 방지한다.

synchronized 한정자가 보이는 메서드는 스레드 안전하다?

❌  이 주장은 스레드 안전성은 모 아니면 도 라는 오해에서 비롯된 것.

• 스레드 안전성에도 수준이 나뉘는데,
  멀티스레드 환경에서도 API 를 안전하게 사용하려면 스레드 안전성 수준을 정확하게 명시해야 한다.

스레드 안정성 단계

1. 불변(immutable)

• 이 클래스의 인스턴스는 마치 상수와 같아서 외부 동기화도 필요 없음.
  • e.g. String, Long, BigInteger

2. 무조건적 스레드 안전(unconditionally thread-safe)

• 이 클래스의 인스턴스는 수정될 수 있으나, 내부에서 충실히 동기화하여 별도의 외부 동기화 없이 동시에 사용해도 안전.
  • e.g. AtomicLong, ConcurrentHashMap

3. 조건부 스레드 안전(conditionally thread-safe)

• 무조건적 스레드 안전과 같으나, 일부 메서드는 동시에 사용하려면 외부 동기화 필요

  • e.g. Collections.synchronized 래퍼 메서드가 반환한 컬렉션들이 여기 속한다.

    (이 컬렉션들이 반환한 반복자는 외부에서 동기화해야 한다.)

4. 스레드 안전하지 않음(not thread-safe)

• 이 클래스의 인스턴스는 수정될 수 있다.
• 동시에 사용하려면 각각의 메서드 호출을 클라이언트가 선택한 외부 동기화 메커니즘으로 감싸야 한다.
  • e.g. ArrayList, HashMap

5. 스레드 적대적(thread-hostile)

• 이 클래스는 모든 메서드 호출을 외부 동기화로 감싸더라도 멀티스레드 환경에서 안전하지 않다.
• 이 수준의 클래스는 일반적으로 정적 데이터를 아무 동기화 없이 수정.
• 고의적으로 만들지는 않겠지만, 만약 스레드 적대적으로 밝혀진 클래스나 메서드는 재배포하거나 사용 자제(deprecated) API 로 지정한다.

스레드 안전성 애너테이션을 활용하자.

• 위에 분류는 [JCIP, 자바 병렬 프로그래밍]에 나오는 스레드 안전성 애너테이션과 대략 매칭된다.
  (스레드 적대적만 빼면)

• @immutable

• @threadsafe

• @NotThreadSafe

특히, 조건부 스레드 안전한 클래스는 주의해서 문서화해야 한다!

• 어떤 순서로 호출할 때 외부 동기화가 필요한지, 그리고 그 순서로 호출하려면 어떤 락을 얻어야 하는지 알려줘야 한다.
• 일반적으로 인스턴스 자체를 락으로 얻지만 예외도 있다.

Collections.synchronizedMap 의 좋은 예시

• Collections.synchronizedMap 의 API 문서 에는 다음과 같이 써 있다.

/** synchronizedMap이 반환한 맵의 컬렉션 뷰를 순회하려면 
반드시 그 맵을 락으로 사용해 수동으로 동기화하라
**/
Map<K, V> m = Collections.synchronizedMap(new HashMap<>());
Set<K> s = m.keySet(); // 동기화 블록 밖에 있어도 된다.
...
synchronized(m) { // s가 아닌 m을 사용해 동기화해야 한다!
   for (K key : s)
       key.f();
}
// 이대로 따르지 않으면 동작을 예측할 수 없다.

• 클래스의 스레드 안전성은 보통 클래스의 문서화 주석에 기재하지만, 독특한 특성의 메서드라면 해당 메서드의 주석에 기재하자.
  • 열거 타입은 굳이 불변이라도 쓰지 않아도 된다.
  • 반환 타입만으로는 명확히 알 수 없는 정적 팩터리라면 자신이 반환하는 객체의 스레드 안전성을 반드시 문서화해야 한다.

핵심요약

• 모든 클래스가 자신의 스레드 안전성 정보를 명확히 설명하거나 스레드 안전성 애너테이션을 통해 문서화해야 한다.
• synchronized 한정자는 문서화와 관련이 없다.
• 특히, 조건부 스레드 안전 클래스는 메서드를 어떤 순서로 호출할 때 외부 동기화가 요구되고, 그때 어떤 락을 얻어야 하는지도 알려줘야 한다.