> For the complete documentation index, see [llms.txt](https://develop-footprint.gitbook.io/o/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://develop-footprint.gitbook.io/o/java/effective-java/11/item-82.md).

# item 82) 스레드 안전성 수준을 문서화하라

> 한 메서드를 여러 스레드가 동시 호출할 때 어떻게 동작하는지 클라이언트가 쉽게 알 수 있도록 문서화가 필요하다.

## synchronized 한정자

* synchronized 한정자가 달려있는 메서드는 thread-safe하다고 생각할 수 있지만 사실은 아니다.
* 메서드 선언에 synchronized 한정자를 선언할지는 **구현 이슈일 뿐 API에 속하지 않는다.**
* 스레드 안전성에도 수준이 나뉘므로 멀티스레드 환경에서도 API를 안전하게 사용하려면 **클래스가 지원하는 스레드 안전성 수준을 정확히 명시해야 한다.**

## 스레드 안전성 수준 문서화

* 안전성이 높은순서대로 소개한다.

### 불변(immutable)

* 불변 클래스의 인스턴스는 상수와 같아 외부 동기화가 필요없다.
* 대표적인 예 - String, Long, BigInteger
* @Immutable

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

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

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

* 무조건적 스레드 안전과 같으나, 일부 메서드는 동시에 사용하려면 외부 동기화가 필요하다.
* 대표적인 예 - Collections.synchronized 래퍼 메서드가 반환한 컬렉션
* 어떤 순서로 호출할 때 외부 동기화가 필요한지, 어떤 락을 얻어야 하는지 알려주는 등 문서화에 주의가 필요하다.
* @ThreadSafe

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

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

### 스레드 적대적(thread-hostile)

* 모든 메서드 호출을 외부 동기화로 감싸더라도 안전하지 않은 클래스이다.
* 일반적으로 정적 데이터를 아무 동기화 없이 수정한다.
* 일반적으로 문제를 고쳐 재배포하거나, deprecated API로 지정한다.

> 외부에서 사용할 수 있는 락을 제공할 경우, 메서드 호출을 원자적으로 수행할 수 있으나 동시성 컬렉션과 같은 고성능 동시성 제어 매커니즘과 혼용할 수 없다.

## 비공개 락 객체

* 서비스 거부 공격을 막을 때 사용
* 클래스 바깥에서 볼 수 없어 클라이언트가 동기화에 관여할 수 없다.
* 락 객체를 동기화 대신 객체 안으로 캡슐화한 것이다. (item 15)

> 락 필드는 항상 final으로 선언해 락 객체의 변경 가능성을 최소화해 에러를 방지해야 한다. (item 78)

```tsx
private final Object lock = new Object();

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

* 비공개 락 객체는 **무조건적 스레드 안전 클래스에서만 사용 가능**하다.
* 조건부 스레드 안전 클래스에서는 **클라이언트에게** 특정 호출 순서에 **필요한 락이 무엇인지 알려줘야 하므로** 사용할 수 없다.
* 상속용으로 설계한 클래스(item 19) 에 특히 잘 맞는다. 상속용 클래스에서 자신의 인스턴스를 락으로 사용하는 경우, 하위 또는 상위 클래스가 같은 락을 다른 목적으로 사용하게 되어 서로의 동기화 메커니즘을 깨트릴 수 있는 상황을 방지할 수 있다.