Merge pull request #348 from SujinEmilyCho/week12_sujin

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

11장/82_스레드_안전성_수준을_문서화하라_조수진.md

@@ -0,0 +1,101 @@
+# 아이템 82. 스레드 안정성 수준을 문서화하라
+자바독 기본 옵션에서 생성한 API 문서에는 synchronized 한정자가 포함되지 않는다. 메서드 선언에 synchronized 한정자를 선언할지는 구현 이슈일 뿐 API에 속하지 않는다.
+
+### 클래스가 지원하는 스레드 안전성 수준
+1. 불변(immutabile)
+  - 이 클래스의 인스턴스는 마치 상수와 같아서 외부 동기화도 필요 없다.
+  - ex. String, Long, BigInteger 등
+2. 무조건적 스레드 안전(unconditionally thread-safe)
+  - 이 클래스의 인스턴스는 수정될 수 있으나, 내부에서 충실히 동기화하여 별도의 외부 동기화 없이 동시에 사용해도 안전하다.
+  - ex. AtomicLong, ConcurrentHashMap 등
+3. 조건부 스레드 안전(contiditionally thread-safe)
+  - 무조건적 스레드 안전과 같으나, 일부 메서드는 동시에 사용하려면 외부 동기화가 필요하다
+  - ex. Collections.synchronized 래퍼 메서드가 반환한 컬렉션들이 여기에 속한다(이 컬렉션들이 반환한 반복자는 외부에서 동기화해야 한다)
+4. 스레드 안전하지 않음(not thread-safe)
+  - 이 클래스들의 인스턴스는 수정될 수 있다. 동시에 사용하려면 각각의(혹은 일련의) 메서드 호출을 클라이언트가 선택한 외부 동기화 메커니즘으로 감싸야 한다.
+  - ex. ArrayList, HashMap 같은 기본 컬렉션이 여기 속한다.
+5. 스레드 적대적(thread-hostile)
+  - 이 클래스는 모든 메서드 호출을 외부 동기화로 감싸더라도 멀티스레드 환경에서 안전하지 않다. 이 수준의 클래스는 일반적으로 정적 데이터를 아무 동기화 없이 수정한다. 이런 클래스를 고의적으로 만드는 사람은 없겠지만, 동시성을 고려하지 않고 작성하다 보면 우연히 만들어질 수 있다. 스레드 적대적으로 밝혀진 클래스나 메서드는 일반적으로 문제를 고쳐 재배포하거나 사용 자제(deprecated) API로 지정한다.
+  - ex. 아이템 78의 generateSerialNumber 메서드에 내부 동기화를 생략한 경우
+
+### 스래드 안전성 애너테이션
+- `@Immutable`
+- `@ThreadSafe`: unconditionally thread-safe, conditionalluy thread-safe
+- `@NotThreadSafe`
+
+### 외부 동기화 vs 내부 동기화
+```java
+public class Foo {
+    private int count;
+    public void addToCount() {
+        count++;
+        log.info("count increased to " + count);
+    }
+}
+
+// 외부 동기화
+synchronized (foo) {
+   foo.addToCount();
+}
+```
+
+```java
+// 내부 동기화
+public class Foo {
+    private int count;
+
+		public void addToCount() {
+		    int val;
+		    synchronized (this) {
+		       val = ++count;
+		    }
+		    // this log call should not be synchronized since it does IO
+		    log.info("count increased to " + val);
+		}
+}
+```
+→ 외부 동기화, 내부 동기화를 알아보기 위한 예시일 뿐 실제로는 AtomicInteger을 사용하는 것이 가장 좋다.
+
+### 스레드 안전성 수준 문서화
+- 클래스의 스레드 안전성은 보통 클래스의 문서화 주석에 기재하지만, 독특한 특성의 메서드라면 해당 메서드의 주석에 기재한다
+- 열거 타입은 굳지 불변이라고 쓰지 않아도 된다
+- 반환 타입만으로 명확히 알 수 없는 정적 팩터리라면 자신이 반환하는 객체의 스레드 안전성을 반드시 문서화 해야한다
+- 조건부 스레드 안전한 클래스는 주의해서 문서화해야 한다. 어떤 순서로 호출할 때 욍부 동기화가 필요한지, 그리고 그 순서로 호출하려면 어떤 락 혹은 (드물게) 락들을 얻어야 하는지 알려줘야 한다. 일반적으로 인스턴스 자체를 락으로 얻지만 예외도 있다.
+
+```java
+// Collections.synchronizedMap API 예시
+synchornizedMap이 반환한 맵의 컬렉션 뷰를 순회하려면 반드시 그 맵을 락으로 사용해 수동으로 동기화하라.
+
+Map<K, V> m = Collections.synchronizedMap(new HashMap<>());
+Set<K> s = m.keySet(); // 동기화 불록 밖에 있어도 된다.
+
+synchronized(m) {  // s가 아닌 m을 사용해 동기화 해야한다!
+	for (K key : s)
+		key.f();
+}
+```
+
+### 공개 락
+
+- 클래스가 외부에서 사용할 수 있는 락을 제공하면 클라이언트에서 일련의 메서드 호출을 원자적으로 수행 가능
+- 내부에서 처리하는 고성능 동시성 제어 메터니즘과 혼용할 수 없음(ex. ConcurrentHashMap)
+- 클라이언트가 공개된 락을 오래 쥐고 놓지 않는 서비스 거부 공격(denial-of-service attack)을 수행할 수도 있다
+- 서비스 거부 공격을 막기 위해서 synchronized 메서드 대신 비공개 락 객체를 사용할 수 있다
+
+```java
+private final Object lock = new Object();
+
+public void foo() {
+	synchronized(lock) {
+		...
+	}
+}
+```
+→ 비공개 락 객체는 클래스 바깥에서 볼 수 없으니 클라이언트가 그 객체의 동기화에 관여할 수 없다
+(락 객체를 동기화 대상 객체 안으로 캡슐화)
+⇒ 비공개 락 객체 관용구는 무조건 스레드 안전 클래스에서만 사용할 수 있다
+→ 상속용으로 설계한 클래스에 특히 잘 맞는다
+(상속용 클래스에서 자신의 인스턴스를 락으로 사용한다면, 하위 클래스는 아주 쉽게 의도치않게 기반 클래스의 동작을 방해할 수 있다)
+
+### 정리
+모든 클래스가 자신의 스레드 안전성 정보를 명확히 문서화 해야 한다. 정확한 언어로 정확히 설명하거나 스레드 안전성 애너테이션을 사용할 수 있다. synchronized 한정자는 문서화와 관련이 없다. 조건부 스레드 안전 클래스는 메서드를 어떤 순서로 호출할 때 외부 동기화가 요구되고, 그때 어떤 락을 얻어야 하는지도 알려줘야 한다. 무조건적 스레드 안전 클래스를 작성할 때는 synchronized 메서드가 아닌 비공개 락 객체를 사용하자. 이렇게 해야 클라이언트나 하위 클래스에서 동기화 메커니즘을 깨뜨리는 걸 예방할 수 있고, 필요하다념 낟음에 더 정교한 동시성 제어 메커니즘으로 재구현할 여지가 생긴다.