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

[yeGenieee]

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

여러 스레드가 하나의 메서드를 동시에 호출할 때, 그 메서드가 어떻게 동작하느냐는 클라이언트와 클래스 간의 중요한 계약과도 같다. 만약 API 문서에 아무런 언급이 없다면, 사용자는 나름의 가정을 하고 사용해야 한다. 스레드 안정성이 잘못되면

1. API 문서에 synchronized 한정자

• 메서드 선언에 synchronized 한정자를 선언할지는 구현 이슈일 뿐 API에 속하지는 않는다
• API 문서에 synchronized 한정자가 보인다고 해서 이 메서드가 thread-safe하다고 믿기 어렵다
• 멀티 스레드 환경에서 안전하게 사용하려면 지원하는 스레드 안전성 수준을 정확히 명시해야 한다

2. 스레드 안전성 수준

1. 불변 (immutable)

• 불변 클래스의 인스턴스는 마치 상수와 같아서 외부 동기화가 필요 없다
• ex) String, Long, BigInteger
• 어노테이션 : @Immutable

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

• 무조건적 스레드 안정 클래스의 인스턴스는 수정될 수 있으나, 내부에서 충실히 동기화하여 별도의 외부 동기화 없이 사용해도 안전하다
• ex) AtomicLong, ConcurrentHashMap
• 어노테이션 : @ThreadSafe

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

• 무조건적 스레드 안전과 같으나, 일부 메서드는 동시에 사용하려면 외부 동기화가 필요하다
• ex) Collections.synchronized wrapper 메서드가 반환한 컬렉션들
• 어노테이션 : @ThreadSafe

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

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

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

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

3. Conditionally Thread-safe 의 문서화

• 조건부 스레드 safe 클래스는 주의하여 문서화해야 한다.
• 어떤 순서로 호출할 때 외부 동기화가 필요한지, 그 순서로 호출하려면 어떤 락 혹은 락들을 얻어야하는지를 명시해주어야 한다
• ex) Collections.synchronizedMap 의 API 문서

  /**
  * It is imperative that the user manually synchronize on the returned
  * map when iterating over any of its collection views
  * 반환된 맵의 콜렉션 뷰를 순회할 때 반드시 그 맵으로 수동 동기화하라
  * 
  *  Map m = Collections.synchronizedMap(new HashMap());
  *      ...
  *  Set s = m.keySet();  // Needn't be in synchronized block
  *      ...
  *  synchronized (m) {  // Synchronizing on m, not s!
  *      Iterator i = s.iterator(); // Must be in synchronized block
  *      while (i.hasNext())
  *          foo(i.next());
  *  }
  */

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

4. Lock 제공

• 외부에서 사용할 수 있는 락을 제공하면 클라이언트에서 메서드 호출을 원자적으로 수행할 수 있다
• 하지만, 내부에서 처리하는 고성능 동시성 제어 메커니즘과는 혼용이 안된다
• 즉, ConcurrentHashMap과는 사용할 수 없다는 뜻
• 클라이언트가 공개된 락을 오래 쥐고 놓지않는 서비스 거부 공격 (Denial-of-service Attack)을 수행할 수 있다
  • synchronized 메서드도 공개된 락에 속한다
• 그렇기 때문에 비공개 락 객체를 사용해야 한다

  
  private final Object lock = new Object();

public void someMethod() { synchronized(lock) { // do something } }

- lock 필드는 항상 **`final`** 로 선언해야 한다
    - final로 선언하면 우연히라도 락 객체가 교체되는 일을 예방할 수 있다