Files

T

DongHyeonka d71669eb59 fix: 하네스 제거 및 keycloak 문서 보강

2026-07-25 12:53:13 +09:00

11 KiB

Raw Permalink Blame History

title, source_type, url, archive_url, status, confidence, tags, related_branches, related_projects, created, last_reviewed

title

source_type

url

archive_url

status

confidence

Caffeine — AsyncLoadingCache & cache stampede prevention

Layer: raw/official-docs/ — Caffeine GitHub Wiki "Population" 페이지 (verbatim 발췌) + 관련 보조 인용 (Refresh, Spring @Cacheable Javadoc).

Parent / 활용 branch (필수)

Branch	이 자료가 정당화하는 결정
raw/branch-notes/feature-cache-consistency-contract	ca-tmpl single-instance stampede 방지에 Caffeine `LoadingCache` / `AsyncLoadingCache` 또는 Spring `@Cacheable(sync=true)` 채택 근거

컨텍스트 / 왜 저장했는지

ca-tmpl single-instance stampede 방지 결정 "Caffeine local lock" 의 근거. LoadingCache / AsyncLoadingCache 의 stampede 방지 메커니즘과 Spring @Cacheable sync=true 와의 관계를 명시.

출처 / Source

원본 URL (Wiki "Population" 페이지): https://github.com/ben-manes/caffeine/wiki/Population
보조 페이지: Caffeine Wiki — "Refresh", "Specification"
보조 자료: Spring Framework @Cacheable Javadoc (sync attribute)
저자 / 조직: Ben Manes (Caffeine 저자) / Caffeine project
발행일: 지속 갱신 (GitHub Wiki)
마지막 확인일: 2026-05-27

핵심 인용 / Key quotes (verbatim)

Caffeine Wiki "Population" — 2026-05-27 fetch 로 확인된 인용:

[§LoadingCache] "A LoadingCache is a Cache built with an attached CacheLoader."

[§AsyncLoadingCache] "A AsyncLoadingCache is a AsyncCache built with an attached AsyncCacheLoader."

[§Asynchronous Computation] "A AsyncCache is a Cache variant that computes entries on an Executor and returns a CompletableFuture."

[§CacheLoader Options] "A CacheLoader should be supplied when the computation is best expressed in a synchronous fashion." / "Alternatively, a AsyncCacheLoader should be supplied when the computation is expressed asynchronously and returns a CompletableFuture."

[§Bulk Operations] "By default, getAll will issue a separate call to CacheLoader.load for each key which is absent from the cache."

보조 인용 (별도 페이지 — 본 fetch 로는 verbatim 미확인, 원래 raw 작성 시점 수집본 보존):

[Caffeine Wiki "Refresh" — needs-confirmation] "refreshAfterWrite reloads asynchronously, returning the old value during reload. Combined with AsyncLoadingCache, refresh does not block readers." (2026-05-27 Wiki Population fetch 에서는 verbatim 미확인 — Refresh 별도 페이지 재확인 필요)

[Spring Framework @Cacheable Javadoc — sync attribute] "sync=true instructs the cache abstraction to synchronize the invocation of the underlying method, if several threads are attempting to load a value for the same key. Only one invocation is performed; others wait." (별도 출처 — Caffeine wiki 가 아님)

Claims Extracted / 추출된 주장

본 raw 의 1차 출처는 Caffeine Wiki "Population". CAFFEINE-POP-C* prefix.

Claim ID	Claim (이 자료가 직접 말하는 것)	Evidence quote	Strength	Applies to	Does not prove
CAFFEINE-POP-C1	`LoadingCache` = `CacheLoader` 가 attach 된 `Cache` 변형	[§LoadingCache] "A `LoadingCache` is a `Cache` built with an attached `CacheLoader`."	`official-vendor-doc`	Caffeine 2.x/3.x `LoadingCache` API 사용	"동일 key 동시 miss 시 single load 직렬화" 메커니즘 자체는 본 인용으로 직접 증명 안 됨 — 별도 Caffeine 동작 명세 또는 `CacheLoader.load` 계약 확인 필요
CAFFEINE-POP-C2	`AsyncLoadingCache` = `AsyncCacheLoader` 가 attach 된 `AsyncCache` 변형	[§AsyncLoadingCache] "A `AsyncLoadingCache` is a `AsyncCache` built with an attached `AsyncCacheLoader`."	`official-vendor-doc`	Caffeine async API 사용	in-flight `CompletableFuture` 가 같은 key 동시 요청에 공유되는지 / 실패 future 의 자동 제거 여부는 본 인용 범위 밖
CAFFEINE-POP-C3	`AsyncCache` 는 `Executor` 위에서 entry 를 계산하고 `CompletableFuture` 를 반환	[§Asynchronous Computation] "A `AsyncCache` is a `Cache` variant that computes entries on an `Executor` and returns a `CompletableFuture`."	`official-vendor-doc`	Caffeine `AsyncCache.get(key, loader)` 호출	Executor 의 기본 구현 (ForkJoinPool 등) 은 본 인용으로 명시 안 됨 — Caffeine `Specification` 페이지 별도 확인
CAFFEINE-POP-C4	계산이 동기적이면 `CacheLoader`, 비동기적이고 `CompletableFuture` 반환이면 `AsyncCacheLoader` 사용	[§CacheLoader Options] "A `CacheLoader` should be supplied when the computation is best expressed in a synchronous fashion." / "Alternatively, a `AsyncCacheLoader` should be supplied when the computation is expressed asynchronously and returns a `CompletableFuture`."	`official-vendor-doc`	loader 선택 결정	"어느 쪽이 stampede 방지 측면에서 더 강력한지" 는 본 인용 범위 밖
CAFFEINE-POP-C5	`getAll` 의 기본 동작은 cache 에 없는 각 key 에 대해 `CacheLoader.load` 를 개별 호출	[§Bulk Operations] "By default, `getAll` will issue a separate call to `CacheLoader.load` for each key which is absent from the cache."	`official-vendor-doc`	Caffeine `Cache.getAll(keys)` 호출	bulk load 최적화 (예: `loadAll` override) 의 효과는 본 인용으로 직접 증명 안 됨
CAFFEINE-POP-C6	`refreshAfterWrite` 는 비동기 reload, 진행 중 old value 반환. `AsyncLoadingCache` 와 결합 시 reader 를 block 하지 않음	[Wiki "Refresh"] "`refreshAfterWrite` reloads asynchronously, returning the old value during reload. Combined with `AsyncLoadingCache`, refresh does not block readers."	`needs-confirmation` (원 raw 수집본; 2026-05-27 Population 페이지 fetch 에서는 verbatim 미발견 — Refresh 별도 페이지 재fetch 필요)	Caffeine refresh 모드	reload 실패 시 old value 의 유효 기간은 본 인용 범위 밖
SPRING-CACHEABLE-C1	Spring `@Cacheable(sync=true)` 는 같은 key 에 대해 여러 thread 가 동시에 load 시도할 때 underlying method 호출을 1회로 동기화. 나머지는 대기	[Spring `@Cacheable` Javadoc — `sync` attribute] "`sync=true` instructs the cache abstraction to synchronize the invocation of the underlying method, if several threads are attempting to load a value for the same key. Only one invocation is performed; others wait."	`official-vendor-doc` (Spring Framework reference Javadoc; Caffeine wiki 아님)	Spring Cache abstraction 사용 + Caffeine backend	이 동기화가 Caffeine 내부 lock 으로 위임되는지 vs Spring 자체 lock 인지는 본 인용으로 직접 증명 안 됨 — Spring `CaffeineCache` 구현 확인 필요

Strength 적용 메모

official-vendor-doc: Caffeine GitHub Wiki 는 저자 (Ben Manes) 가 직접 유지하는 공식 문서. official-standard (RFC) 가 아니므로 한 단계 아래.
needs-confirmation: 본 fetch 에서 verbatim 으로 확인 불가능한 인용. 원 raw 작성 시점 수집본을 보존하되 별도 fetch 로 재확인 필요.

Usage Boundaries / 적용 경계

이 자료가 직접 증명하는 것:
- CAFFEINE-POP-C1~C5: Caffeine LoadingCache/AsyncLoadingCache 의 API 형태 + getAll 기본 동작
- SPRING-CACHEABLE-C1: Spring @Cacheable(sync=true) 의 동기화 의미 (Spring Javadoc 기준)
이 자료가 증명하지 않는 것:
- Caffeine LoadingCache 가 동일 key 동시 miss 시 backend 호출을 정확히 1회로 직렬화한다는 보장: 본 Population 페이지 fetch 에서 verbatim 인용 미확보. ca-tmpl Required test 검증 시 별도 동작 테스트 + Caffeine source 코드 (BoundedLocalCache#doComputeIfAbsent) 확인 필요
- in-flight CompletableFuture 공유 / 실패 future 자동 제거 메커니즘: 본 fetch 범위 밖
- Spring @Cacheable(sync=true) 가 Caffeine backend 와 결합 시 어느 layer 에서 lock 이 걸리는지 (Spring 자체 lock vs Caffeine 내부): 별도 검증 필요
내 프로젝트에 적용하려면 추가 확인이 필요한 것:
- ca-tmpl Required test ("동일 key 동시 cache miss → backend 호출 1회") 의 actual 검증
- multi-instance 환경에서 본 메커니즘이 적용 안 되는 점 (instance 별 별도 load) — Redisson RLock 등 분산 잠금으로 승격 필요한 분기

메모 / Notes (내 프로젝트 해석 — PRESERVED)

본 섹션은 자료 직접 인용 아님. ca-tmpl 결정 컨텍스트 해석. 원 raw 의 해석을 보존하되 verifiability gap 을 명시.

single-instance stampede 방지 mechanism:
- Caffeine LoadingCache 자체가 같은 key 에 대한 동시 load 를 1회로 직렬화 (널리 알려진 동작이나, 본 Population 페이지 fetch 만으로는 verbatim 증거 없음 — needs-confirmation). 외부 lock 불필요.
- Spring abstraction 을 쓸 때는 @Cacheable(sync=true) 로 동등 효과. 내부적으로 Caffeine get(key, loader) 가 호출됨 (Spring CaffeineCache 구현 가정 — 본 raw 자료로 직접 증명 안 됨).
ca-tmpl Required test 와의 정합성:
- "동일 key 에 대해 동시 cache miss 시 backend 호출 1회로 제한" 검증 → Caffeine LoadingCache 또는 @Cacheable(sync=true) 둘 다 통과 가정.
- test 에서 명시한 (a) sync=true 또는 (b) AsyncLoadingCache 또는 (c) Redisson RLock wrap 분기 중 (a)(b) 가 Caffeine 분기, (c) 가 multi-instance 분기.
장점:
- in-process, network round-trip 없음 → 1µs급 hit latency.
- Window TinyLFU eviction policy 로 LRU 보다 hit-rate 우수 (Caffeine 논문 인용 영역 — 본 wiki 페이지 직접 증명 아님).
단점 (ca-tmpl 입장):
- multi-instance 에서는 의미 없음 — instance 별로 별도 load 가 일어남. HPA 환경에서는 RLock 으로 승격 필요.
- JVM restart 시 cache cold start. 안 가져갈 hot key 가 cold path 를 거치면 backend burst.
시사점: ca-tmpl 의 "single-instance Caffeine, multi-instance Redisson" 분기는 scope 에 맞춘 도구 차등화. write-back/distributed mode 를 Caffeine 에 요구하지 않음 (out of scope).

같은 주제 다른 raw:
- (Caffeine Refresh / Specification 별도 페이지 — 미작성)
인용하는 branch:
- raw/branch-notes/feature-cache-consistency-contract
적용 contract:
- raw/project-notes/ca-skeleton-operational-contract (Cache consistency 그룹)
인용하는 wiki: (미작성)

11 KiB Raw Permalink Blame History