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

한 메서드를 여러 쓰레드가 동시에 호출할 때, 해당 메서드가 어떻게 동작하는지는 해당 클래스와 이를 사용하는 클라이언트 간의 중요한 정보입니다.

이러한 정보가 API 문서에 포함되지 않으면 클래스 사용자는 이 관계를 추측해야 합니다.

그러나 이러한 추측이 틀릴 경우 클라이언트 프로그램은 동기화를 충분히 하지 못하거나 과도하게 동기화하여 성능 문제나 오류를 발생시킬 수 있습니다.

따라서 API 문서에 이러한 정보를 명시하는 것이 중요합니다.

 

synchronized 한정자

• API 문서에 synchronized 한정자가 있는 메서드는 안전하다고 간주하는 개발자들이 많은데, 이는 몇 가지 이유로 틀린 생각
  • 메서드 선언에 synchronized 한정자를 선언할지는 구현 이슈일 뿐 API에 속하지 않기 때문에 JavaDoc의 기본 옵션에서 생성한 API 문서에는 synchronied 한정자가 포함되지 않기 때문에 이 것만으로 해당 메서드가 thread-safe 하다고 믿기 어려움
  • synchronized 유무로 thread-safe 함을 알 수 있다는 주장은 `쓰레드 안전성은 모 아니면 도`라는 오해에 뿌리를 둔 발언
    • 쓰레드 안전성 수준이 나뉘기 때문에 모 아니면 도가 아님
    • 따라서 멀티 쓰레드 환경에서 API를 안전하게 사용하기 위해서는 클래스가 지원하는 쓰레드 안전성 수준을 정확히 명시해야 함

 

쓰레드 안전성 수준

• 불변(immutable)
• 무조건적 쓰레드 안전(unconditionally thread-safe)
• 조건부 쓰레드 안전(conditionally thread-safe)
• 쓰레드 안전하지 않음(not thread-safe)
• 쓰레드 적대적(thread-hostile)

 

1. 불변(immutable) [@Immutable]

 

• 해당 클래스의 인스턴스는 마치 상수와 같아 외부 동기화가 필요 없음
• ex) String, Long, BigInteger

 

2. 무조건적 쓰레드 안전(unconditionally thread-safe) [@ThreadSafe]

 

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

 

3. 조건부 쓰레드 안전(conditionally thread-safe) [@ThreadSafe]

 

• 무조건적 쓰레드 안전과 같으나, 일부 메서드는 동시 사용 시 외부 동기화 필요
• 해당 클래스의 경우 주의해서 문서화 필요 (외부 동기화가 필요한 일부 메서드 반드시 명시)
  • 어떤 순서로 호출할 때 외부 동기화가 필요한지, 그리고 그 순서로 호출하려면 어떤 lock 혹은 lock들을 획득해야 하는지 알려줘야 함
  • 일반적으로 인스턴스 자체를 락으로 얻지만 예외도 있음
    • Collections.synchronizedSet 주석을 보면 synchronizedSet이 반환한 Set의 컬렉션 뷰를 순회하려면 반드시 그 Set을 락으로 사용해 수동으로 동기화하라

 

 

4. 쓰레드 안전하지 않음(not thread-safe) [@NotThreadSafe]

 

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

 

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

 

• 해당 클래스는 모든 메서드 호출을 외부 동기화로 감싸더라도 멀티 쓰레드 환경에서 thread-safe 하지 않음
• 이 수준의 클래스는 일반적으로 정적 데이터를 아무 동기화 없이 수정
• 고의로 이런 클래스를 생성하는 경우는 없겠지만, 동시성을 고려하지 않고 개발하다 보면 만들어질 수 있음
• 쓰레드 적대적으로 밝혀진 클래스나 메서드는 일반적으로 문제를 고쳐 재배포하거나 사용 자제 API로 지정해야 함

 

쓰레드 안전성 문서화 원칙

• 클래스의 쓰레드 안전성은 보통 클래스의 문서화 주석에 기재하지만, 독특한 특성의 메서드일 경우 해당 메서드의 주석에 기재하는 것을 권장
• 반환 타입만으로는 명확히 알 수 없는 정적 팩토리라면 자신이 반환하는 객체의 쓰레드 안전성을 반드시 문서화하는 것을 권장
  • ex) Collections.synchronizedSet

 

비공개 락 객체 관용구

• 클래스가 외부에서 사용할 수 있는 락을 제공할 경우 클라이언트에서 일련의 메서드 호출을 원자적으로 수행할 수 있지만 이 유연성에는 대가가 따름
  • 내부에서 처리하는 고성능 동시성 제어 메커니즘과 혼용할 수 없음
  • 위와 같은 이유로 ConcurrentHashmap 같은 동시성 컬렉션과는 함께 사용하지 못함
  • 추가로 클라이언트가 공개된 락을 오래 쥐고 놓지 않는 서비스 거부 공격(denial-of--service attack)을 수행할 수도 있음
  • 서비스 거부 공격을 막기 위해서는 synchronized 메서드 대신 비공개 락 객체를 사용해야 함

 

• 비공개 락 객체는 클래스 바깥에서는 볼 수 없으므로 클라이언트가 해당 객체의 동기화에 관여할 수 없음
  • 즉, 락 객체를 동기화 대상 객체 안으로 캡슐화한 것

 

• 비공개 락 객체 관용구는 무조건적 쓰레드 안전(unconditionally thread-safe) 클래스에서만 사용할 수 있음
• 조건부 쓰레드 안전(conditionally thread-safe) 클래스에서는 특정 호출 순서에 필요한 락이 무엇인지를 클라이언트에게 알려줘야 하므로 해당 관용구를 사용할 수 없음
• 비공개 락 객체 관용구는 상속용으로 설계한 클래스에 특히 잘 맞음
  • 상속용 클래스에서 자신의 인스턴스를 락으로 사용할 경우 하위 클래스는 의도치 않게 기반 클래스의 동작을 방해할 수 있음
  • 즉, 같은 락을 다른 목적으로 사용하게 되어 하위 클래스와 기반 클래스는 `서로가 서로를 훼방 놓는` 상태에 빠짐
  • 비공개 락 객체 관용구 사용 시 기반 클래스의 락에 애초에 접근할 수 없으므로 상속용으로 좋음

 

정리

• 모든 클래스가 자신의 쓰레드 안전성 정보를 명확히 문서화하자
• 정확한 언어로 명확히 설명하거나 @Immutable, @ThreadSafe, 그리고 @NotThreadSafe과 같은 쓰레드 안전성 어노테이션을 사용하자
• 조건부 쓰레드 안전 클래스는 어떤 순서로 호출할 때 외부 동기화가 요구되고 그 때 어떤 락을 얻어야 하는지도 알려주자
• 무조건적 쓰레드 안전 클래스를 작성할 때는 synchronized 메서드가 아닌 비공개 락 객체를 사용하자
  • 이렇게 해야 클라이언트나 하위 클래스에서 동기화 메커니즘을 깨는 것을 방지하고 더 정교한 동시성 제어 메커니즘으로 재구현할 여지가 생기기 때문

 

참고

이펙티브 자바