[Spring] 비동기 환경에서 ThreadLocal 관리

해당 포스팅은 비동기로 동작하는 스프링 프로젝트 환경에서 안전한 Context 전파 전략을 도입하기 위한 ThreadLocal과 InheritableThreadLocal 고찰에 대한 내용입니다.

---

1. 문제 배경

• 시스템에서 사용자 요청 시 고객 정보를 ThreadLocal에 저장하고, 요청 처리 전체 과정에서 일관되게 유지하고자 함
• 하지만, 비동기 작업 또는 스레드 풀 환경에서는 ThreadLocal의 한계로 인해 고객 정보가 전파되지 않거나, 누수/섞임 등의 문제가 발생 가능.

---

2. InheritableThreadLocal 도입 고려 및 문제 분석

InheritableThreadLocal은 자식 스레드가 생성될 때 부모 스레드의 값을 자동으로 복사한다는 장점을 가지고 있습니다.

 

2.1. InheritableThreadLocal의 내부 구조

public class AccountContext {
    public static final InheritableThreadLocal<AccountInfo> accountThreadLocal = new InheritableThreadLocal<>();
}

Thread-Main.inheritableThreadLocals
↳ key: accountThreadLocal → value: AccountInfo@0x123
Thread-Sub.inheritableThreadLocals
↳ key: accountThreadLocal → value: AccountInfo@0x123

• userThreadLocal은 static으로 전역 1개
• 각 스레드는 자신의 ThreadLocalMap을 가짐
• ThreadLocalMap의 key는 동일한 userThreadLocal 인스턴스
• 이 구조로 인해, 같은 키로 다른 스레드의 값을 구분해서 접근 가능

 

2.2. 문제점 및 한계

1) 값은 복사되지만 참조가 공유됨

• mainThread → subThread로 전파 시, 값은 복사되지만 같은 객체 참조를 가짐.
• 즉, 자식 스레드에서 객체 내부 값을 변경하면, 부모에게도 영향을 미침.

ThreadLocalMap
- mainThread : AccountInfo@0x123
- subThread : AccountInfo@0x123

 

2) 객체 자체를 새로 생성하면 부모/자식 값이 분리

• 자식 스레드에서 new AccountInfo(...)로 새로운 객체를 set하면 부모와는 다른 값으로 분리됨.
• 그러나 이를 위해선 개발자가 명시적으로 객체를 새로 생성해야 하며, 자동 전파의 의미가 퇴색됨.

3) 메모리 관리 문제

• ThreadLocalMap은 각 스레드마다 존재
• mainThread에서 ThreadLocal.remove() 해도 자식 스레드의 값은 여전히 남아 있음.
• 자식 스레드에서 직접 remove하지 않으면 메모리 누수 위험 존재

4) 스레드 풀 환경에서는 값이 전파되지 않음

• InheritableThreadLocal은 스레드 생성 시점에만 값 복사됨.
• 스레드 풀은 기존 스레드를 재사용하기 때문에, 새로 생성되지 않으면 값이 전파되지 않음.
  • 일반적으로 비동기 동작을 위해서 스레드 풀을 만들어서 사용.

---

3. InheritableThreadLocal 보완 시도 및 한계

3.1. 불변 객체 사용

• 내부 상태가 바뀌지 않도록 설계
  • 이미 값이 복사되어 들어 있으면 새로 생성 불가능하도록 처리
  • setter 모두 제거, final 필드 사용

3.2. 전파 시 수동 복사

• 자식 스레드 생성 시, 수동으로 복사된 객체를 설정

3.3. 명시적 remove() 처리

• 자식 스레드가 종료되기 전에 ThreadLocal.remove() 호출로 메모리 누수 방지

 

하지만, 해당 방법들은 결국 라이프 사이클을 직접 관리할 수 없으니, 아래와 같은 한계가 여전히 남아있습니다.

• 자동 전파의 의미가 퇴색됨
• 의도치 않은 값의 복사에 대해선 명시적 remove 처리가 어려움

따라서, 스레드 풀 사용 환경에서 InheritableThreadLocal 사용 말고 다른 방법을 찾아보았습니다.

---

4. 결론: TaskDecorator + 일반 ThreadLocal

4.1. TaskDecorator를 활용하여 ThreadLocal값을 유지

• 일반 ThreadLocal 사용
• TaskDecorator를 통해 부모 스레드의 값을 수동으로 복사
• 작업 종료 후 finally에서 remove()를 수행하여 GC 유도

public class AccountContextTaskDecorator implements TaskDecorator {
    @Override
    public Runnable decorate(Runnable runnable) {
        AccountInfo context = AccountContext.get(); // ThreadLocal에서 값 복사
        return () -> {
            try {
                AccountContext.set(context); // 복사한 값 설정
                runnable.run();              // 원래 작업 실행
            } finally {
                AccountContext.clear();      // 누수 방지를 위해 remove()
            }
        };
    }
}

 

 

4.2. ThreadPool이 해당 TaskDecorator를 사용하도록 등록

@Configuration
public class AsyncConfig {

    @Bean(name = "asyncExecutor")
    public ThreadPoolTaskExecutor asyncExecutor() {
        ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor();
        executor.setCorePoolSize(2);                  // 기본 쓰레드 수
        executor.setMaxPoolSize(8);                   // 최대 쓰레드 수
        executor.setQueueCapacity(100);                // 대기 큐 크기
        executor.setThreadNamePrefix("async-thread-"); // 쓰레드 이름 prefix
        executor.setTaskDecorator(new AccountContextTaskDecorator()); // 커스텀 TaskDecorator 등록
        executor.initialize();
        return executor;
    }
}

 

 

결과적으로, 아래와 같이 안전하게 고객 정보를 관리할 수 있습니다.

• 명확하게 Context 생명주기를 관리
• 비동기 환경에서도 사용자 정보를 안전하게 전파 가능
• GC 누수를 방지

---

5. 테스트 코드

해당 코드는 위와 같은 결과를 도출하기 위해 진행한 테스트 코드입니다.

class AccountContextTest {
    static class AccountInfo {
        private String name;
        public AccountInfo(String name) {
            this.name = name;
        }
        public String getName() {
            return name;
        }
        public void setName(String name) {
            this.name = name;
        }
    }
    private static final InheritableThreadLocal<AccountInfo> accountThreadLocal = new InheritableThreadLocal<>();
    @DisplayName("자식이 필드를 변경하면 부모의 필드도 같이 변경됨")
    @Test
    void testInheritableThreadLocal_change_field_same() throws InterruptedException {
        // mainThread에서 값 셋팅
        AccountInfo accountInfo = new AccountInfo("main");
        accountThreadLocal.set(accountInfo);
        System.out.println("[" + Thread.currentThread().getName() + "] main이 설정 => " + accountThreadLocal.get().getName());
        // subThread에서 필드 값 변경
        Thread sub = new Thread(() -> {
            AccountInfo inherited = accountThreadLocal.get();// 부모로부터 참조 복사됨
            System.out.println("[" + Thread.currentThread().getName() + "] main에서 물려받음 => " + accountThreadLocal.get().getName());
            inherited.setName("sub");
            System.out.println("[" + Thread.currentThread().getName() + "] sub가 변경함 => " + accountThreadLocal.get().getName());
        });
        sub.start();
        sub.join();// subThread 종료 대기// mainThread에서 다시 값 조회 (자식이 변경한 값 확인)
        System.out.println("[" + Thread.currentThread().getName() + "] main도 변경됨 => " + accountThreadLocal.get().getName());
        // 결과: 변경되어 있어야 함
        assertThat(accountThreadLocal.get().getName()).isEqualTo("sub");
    }
    @DisplayName("자식이 객체를 변경하면 자식만 변경됨")
    @Test
    void testInheritableThreadLocal_change_object_diff() throws InterruptedException {
        // mainThread에서 값 셋팅
        AccountInfo accountInfo = new AccountInfo("main");
        accountThreadLocal.set(accountInfo);
        System.out.println("[" + Thread.currentThread().getName() + "] main이 설정 => " + accountThreadLocal.get().getName());
        // subThread에서 객체 변경
        Thread sub = new Thread(() -> {
            System.out.println("[" + Thread.currentThread().getName() + "] main에서 물려받음 => " + accountThreadLocal.get().getName());
            AccountInfo subAccountInfo = new AccountInfo("sub");
            accountThreadLocal.set(subAccountInfo);
            System.out.println("[" + Thread.currentThread().getName() + "] sub에 새로운거 넣음 => " + accountThreadLocal.get().getName());
        });
        sub.start();
        sub.join();
        // mainThread에서 확인
        System.out.println("[" + Thread.currentThread().getName() + "] main은 그대로 => " + accountThreadLocal.get().getName());
        // 결과: 변경X
        assertThat(accountThreadLocal.get().getName()).isEqualTo("main");
    }
/**
     * accountThreadLocal과 스레드 풀
     *@throwsInterruptedException     */
    @DisplayName("스레드 전파 후 main스레드 먼저 종료시 ThreadLocal값이 살아있음")
    @Test
    void testInheritableThreadLocal_main_terminate_sub_alive() throws InterruptedException {
        ExecutorService executor = Executors.newFixedThreadPool(1);
        // MainThread에서 설정
        accountThreadLocal.set(new AccountInfo("main"));
        System.out.println("[" + Thread.currentThread().getName() + "] set name = main");
        // 비동기 실행 (InheritableThreadLocal은 스레드 생성 시만 복사되므로 주의)
        executor.submit(() -> {
            // 이 쓰레드는 풀에서 재사용되므로 InheritableThreadLocal이 null일 수 있음
            AccountInfo accountInfo = accountThreadLocal.get();
            System.out.println("[" + Thread.currentThread().getName() + "] inherited? " + (accountInfo != null ? accountInfo.getName() : "null"));
            try {
                try {
                    Thread.sleep(3000);// 오래 걸리는 작업
                } catch (InterruptedException e) {
                    throw new RuntimeException(e);
                }
                System.out.println("[" + Thread.currentThread().getName() + "] 작업 완료, 읽은 값 = " + accountThreadLocal.get().getName());
            } finally {
                // 꼭 정리해줘야 함!
                accountThreadLocal.remove();
                System.out.println("[" + Thread.currentThread().getName() + "] ThreadLocal 정리 완료, 읽은 값 = " + accountThreadLocal.get());
            }
        });
        // main은 바로 응답 (remove)
        System.out.println("[" + Thread.currentThread().getName() + "] 작업 완료, 읽은 값 = " + accountThreadLocal.get().getName());
        accountThreadLocal.remove();
        System.out.println("[" + Thread.currentThread().getName() + "] remove 완료");
        System.out.println("[" + Thread.currentThread().getName() + "] remove 완료, 읽은 값 = " + accountThreadLocal.get());
        // main 대기
        Thread.sleep(4000);
        executor.shutdown();
    }
    @DisplayName("스레드 풀에서 꺼내온 스레드는 값이 복사 안됨")
    @Test
    void testInheritableThreadLocal_pool_no_inherit() throws InterruptedException {
        ExecutorService executor = Executors.newFixedThreadPool(1);
        // MainThread에서 설정
        accountThreadLocal.set(new AccountInfo("main"));
        System.out.println("[" + Thread.currentThread().getName() + "] set name = main");
        // 2번 실행 -> 1번은 새로 생성, 2번은 꺼내와서 사용
        for(int i=0;i<2;i++) {
            int cnt = i;
            executor.submit(() -> {
                try {
                    AccountInfo accountInfo = accountThreadLocal.get();
                    if (cnt == 0) {
                        System.out.print("첫번째는 새로 생성됨 => ");
                    } else {
                        System.out.print("두번째는 풀에서 꺼내옴 => ");
                    }
                    System.out.println("[" + Thread.currentThread().getName() + "] inherited? " + (accountInfo != null ? accountInfo.getName() : "null"));
                } finally {
                    accountThreadLocal.remove();
                }
            });
        }
        accountThreadLocal.remove();
        Thread.sleep(1000);
        executor.shutdown();
    }
    @DisplayName("스레드 풀 사용 시 TaskDecorator로 복사 후 실행, finally에서 remove 확인")
    @Test
    void testInheritableThreadLocal_sub_finally_remove() throws InterruptedException, ExecutionException {
        ExecutorService executor = Executors.newFixedThreadPool(1);
        accountThreadLocal.set(new AccountInfo("main"));
        System.out.println("[" + Thread.currentThread().getName() + "] 셋팅된 값 = " + accountThreadLocal.get().getName());
        Runnable originalTask = () -> {
            try {
                System.out.println("[" + Thread.currentThread().getName() + "] 복사된 값 = " + accountThreadLocal.get().getName());
            } finally {
                // 꼭 remove 해줘야 메모리 누수 방지됨
                accountThreadLocal.remove();
                System.out.println("[" + Thread.currentThread().getName() + "] remove 완료, 읽은 값 = " + accountThreadLocal.get());
            }
        };
		// TaskDecorator처럼 context 전달
        Runnable decoratedTask = () -> {
            AccountInfo parentContext = accountThreadLocal.get();
            accountThreadLocal.set(parentContext);// 상속처럼 복사
            originalTask.run();
        };
		// 실행
        executor.submit(decoratedTask).get();
		// Main context도 정리
        accountThreadLocal.remove();
        System.out.println("[" + Thread.currentThread().getName() + "] remove 완료, 읽은 값 = " + accountThreadLocal.get());
        assertThat(accountThreadLocal.get()).isNull();
        executor.shutdown();
    }
}

 

---

 

[참고]

• [Java] 스레드 로컬(ThreadLocal)과 상속 가능한 스레드 로컬( InheritableThreadLocal)에 대하여
• ThreadLocal의 내부 동작 방식은 java.lang 소스코드를 참고하여 분석