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

1. API 문서 synchronized 한정자

메서드 선언에 synchronized 한정자를 선언할지는 구현 이슈일 뿐 API에 속하지 않는다.

API 문서에 synchronized 한정자가 보인다고해서 이 메서드가 스레드 안전하다고 믿기 어렵다.

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

 

2. 스레드 안전성 수준

불변(immutable)

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

 

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

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

 

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

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

 

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

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

 

스레드 적대적(thread-hostil)

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

 

3. Conditionally Thread-safe의 문서화

• 어떤 순서로 호출할 때 외부 동기화가 필요한지
• 그 순서로 호출하려면 어떤 락 혹은 락들을 얻어야하는지

Collections.synchronizedMap 문서 예시

synchronizedMap이 반환한 맵의 컬렉션 뷰를 순회하려면 반드시 그 맵을 락으로 사용해 수동으로 동기화하라

코드대로 따르지 않으면 동작을 예측할 수 없다.

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

반환타입만으로 명확히 알 수 없는 정적 팩터리라면 반환 객체의 스레드 안전성을 반드시 문서화 해야한다.

 

4. Lock 제공

외부에서 사용할 수 있는 락을 제공하면 클라이언트에서 메서드 호출을 원자적으로 수행할 수 있다.

• 내부에서 처리하는 고성능 동시성 제어 메커니즘과 혼용이 안된다. (CurrentHashMap과는 사용 X)
• 클라이언트가 공개된 락을 오래 쥐고 놓지 않는 서비스 거부 공격 (denail-of-service attack)을 수행할 수도 있다.
• synchronized 메서드도 공개된 락에 속한다.
• 비공개 락 객체를 사용해야한다!

// 비공개 락 객체, final 선언! : 락 객체 교체 상황 방지를 위함
private final Object lock = new Object();

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

락필드는 항상 final로 선언하라

비공개 락 객체 관용구는 무조건적 스레드 안전 클래스에서만 사용가능하다.

조건부 스레드 안전클래스에서는 특정 호출 순서에 필요한 락을 알려줘야하므로 이 관용구를 사용할 수 없다.