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

[Why]

API 문서에서 동시성에 대한 언급이 없으면 그 클래스 사용자는 나름의 가정을 해야만 한다.

• 그 가정이 틀리면 클라이언트 프로그램은 동기화를 충분히 하지 못하거나(아이템78) 지나치게 한(아이템79) 상태일 것이며, 두 경우 모두 심각한 오류로 이어질 수 있다.
• 자바독이 기본 옵션에서 생성한 API 문서에는 synchronized 한정자가 포함되지 않는다. (구현 이슈일 뿐이기 때문)

스레드 안전성에도 수준이 나뉜다.

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

 

[How]

다음 목록은 스레드 안전성이 높은 순으로 나열한 것이다.

• 불변(immutable): 이 클래스의 인스턴스는 마치 상수와 같아서 외부 동기화도 필요 없다.
  e.g.) String, Long, BigInteger
• 무조건적 스레드 안전(unconditionally thread-safe): 이 클래스의 인스턴스는 수정될 수 있으나, 내부에서 충실히 동기화하여 별도의 외부 동기화 없이 동시에 사용해도 안전하다.
  e.g.) AtomicLong, ConcurrentHashMap
• 조건부 스레드 안전(conditionally thread-safe): 무조건적 스레드 안전과 같으나, 일부 메서드는 동시에 사용하려면 외부 동기화가 필요하다.
  e.g.) Collections.synchronized 래퍼 메서드가 반환한 컬렉션들
• 스레드 안전하지 않음(not thread-safe): 이 클래스의 인스턴스는 수정될 수 있다. 동시에 사용하려면 각각의(혹은 일련의) 메서드 호출을 클라이언트가 선택한 외부 동기화 메커니즘으로 감싸야 한다.
  e.g.) ArrayList, HashMap 같은 기본 컬렉션
• 스레드 적대적(thread-hostile): 이 클래스는 모든 메서드 호출을 외부 동기화로 감싸더라도 멀티스레드 환경에서 안전하지 않다. 이 수준의 클래스는 일반적으로 정적 데이터를 아무 동기화 없이 수정한다. 이런 클래스를 고의로 만드는 사람은 없겠지만, 동시성을 고려하지 않고 작성하다 보면 우연히 만들어질 수 있다. 스레드 적대적으로 밝혀진 클래스나 메서드는 일반적으로 문제를 고쳐 재배포하거나 사용 자제(deprecated) API로 지정한다.
  e.g.) generateSerialNumber 메서드에서 내부 동기화를 생략했을 때

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

• 어떤 순서로 호출할 때 외부 동기화가 필요한지, 그리고 그 순서로 호출하려면 어떤 락 혹은 (드물게) 락들을 얻어야 하는지 알려줘야 한다.

클래스의 스레드 안전성은 보통 클래스의 문서화 주석에 기재하지만, 독특한 특성의 메서드라면 해당 메서드의 주석에 기재하도록 하자.

클래스가 외부에서 사용할 수 있는 락을 제공하면 클라이언트에서 일련의 메서드 호출을 원자적으로 수행할 수 있다. 하지만 이 유연성에는 대가가 따른다.

• 내부에서 처리하는 고성능 동시성 제어 메커니즘과 혼용할 수 없게 된다.
• 또한, 클라이언트가 공개된 락을 오래 쥐고 놓지 않는 서비스 거부 공격(denial-of-service attack)을 수행할 수 있다.
  • 서비스 거부 공격을 막으려면 synchronized 메서드 대신 비공개 락 객체를 사용해야 한다.
  • 비공개 락 객체는 클래스 바깥에서는 볼 수 없으니 클라이언트가 그 객체의 동기화에 관여할 수 없다.
  • 비공개 락 객체 관용구는 무조건적 스레드 안전 클래스에서만 사용할 수 있다.
    (조건부 스레드 안전 클래스에서는 특정 호출 순서에 필요한 락이 무엇인지 클라이언트에게 알려줘야 한다)
  • 비공개 락 객체 관용구는 상속용으로 설계한 클래스(아이템19)에 특히 잘 맞는다.
    (상속용 클래스에서 자신의 인스턴스를 락으로 사용한다면, 하위 클래스는 아주 쉽게, 그리고 의도치 않게 기반 클래스의 동작을 방해할 수 있다)

private final Object lock = new Object();  // 락 객체는 항상 final로 선언하라.

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