item 82. 스레드 안정성 수준을 문서화하라

보통, API 문서에 synchronized가 붙은 메서드는 '스레드 안전'하다는 말이 있다.

하지만!!! 이는 언제나 맞는 말은 아니다.

 

JavaDoc이 기본 옵션에서 생성한 API문서에는 synchronized 한정자가 포함되지 않기 때문이다. (메서드에 synchronized를 붙이고 말고는 구현 이슈일 뿐, API에 속하는 것이 아니기 때문이다.)

 

멀티스레드 환경에서도 API를 안전하게 사용하게 하려면,
클래스가 지원하는 스레드 안전성 수준을 정확히 명시해야 한다.

---

스레드 안전성 수준 나열

( 안전성이 좋은 순서)

 

불변(immutabile)

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

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

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

조건부 스레드 안전(contiditionally thread-safe)

• 무조건적 스레드 안전과 같으나, 일부 메서드는 동시에 사용하려면 외부 동기화가 필요하다
• ex) Collections.synchronized 래퍼 메서드가 반환한 컬렉션 (이 컬렉션들이 반환한 반복자는 외부에서 동기화해야 한다)

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

• 이 클래스들의 인스턴스는 수정될 수 있다.
• 동시에 사용하려면 각각의(혹은 일련의) 메서드 호출을 클라이언트가 선택한 외부 동기화 메커니즘으로 감싸야 한다.
• ex) ArrayList, HashMap 같은 기본 컬렉션

스레드 적대적(thread-hostile)

• 이 클래스는 모든 메서드 호출을 외부 동기화로 감싸더라도 멀티스레드 환경해서 안전하지 않다.
• 이 수준의 클래스는 일반적으로 정적 데이터를 아무 동기화 없이 수정한다.
• 일반적으로 위 클래스나 메서드는 문제를 고쳐서 재배포하거나, 사용 자제 deprecated API로 지정한다.
• ex) generateSerialNumber 메서드에서 내부동기화 생략 시

---

지키면 좋은 것

• 클래스의 스레드 안전성은 보통 클래스의 문서화 주석에 기재하지만, 독특한 특성의 메서드라면 해당 메서드의 주석에 기재한다.
• 열거 타입은 굳이 불변이라고 쓰지 않아도 된다.
• 반환 타입만으로는 명확히 알 수 없는 정적 팩터리라면. 자신이 반환하는 객체의 스레드 안정성을 반드시 문서화해야 한다. 
• 서비스 거부 공격을 막으려면, synchronized 메서드 대신 비공개 락 객체를 사용하자.
  • 비공개 락 객체는 클래스 바깥에서 볼 수 없어 클라이언트가 그 객체의 동기화에 관여할 수 없다.
  • 비공개 락 객체 관용구는 무조건적 스레드 ㅇ나전 클래스에서만 사용할 수 있다.

 

핵심 정리

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