Add AsyncLoader to load and update value periodically

[injae-kim]

Fixes #5506.

Motivation:

AsyncLoader can be useful in the following situations.

• When it is necessary to periodically read and update information from a file such as resolv.conf .
• When data is not valid after a certain period of time, such as an OAuth 2.0 access token.

We already have an implementation for that on AbstractOAuth2AuthorizationGrant.java.
However, I hope to generalize it and add new features to use it in various cases.

Modifications:

• Add AsyncLoader to load and update value periodically

Result:

• Closes Provide a way to load a value periodically or when it expires #5506.
• Now user can load, cache, update value periodically by using AsyncLoader

[github-actions]

🔍 Build Scan® (commit: e9853bb)

Job name	Status	Build Scan®
build-windows-latest-jdk-21	✅	https://ge.armeria.dev/s/vlvmsk4nxn6ti
build-self-hosted-unsafe-jdk-8	✅	https://ge.armeria.dev/s/6ehjatyfi7joq
build-self-hosted-unsafe-jdk-21-snapshot-blockhound	✅	https://ge.armeria.dev/s/us5xkh3tzhr2w
build-self-hosted-unsafe-jdk-17-min-java-17-coverage	✅	https://ge.armeria.dev/s/k4aizbvsrtjpe
build-self-hosted-unsafe-jdk-17-min-java-11	✅	https://ge.armeria.dev/s/uz65j2vquyvs6
build-self-hosted-unsafe-jdk-17-leak	✅	https://ge.armeria.dev/s/xeylalia5akgu
build-self-hosted-unsafe-jdk-11	✅	https://ge.armeria.dev/s/uwlcr4lc2is2y
build-macos-12-jdk-21	✅	https://ge.armeria.dev/s/zicneycd4434w

[ikhoon]

Side note: It is not related to this PR but fallbackTokenProvider is a name that we should only use when a token acquisition fails since it is a fallback.

I think it would be better to remove fallback from the API method. tokenProvider seems clearer.

[codecov]

Codecov Report

Attention: Patch coverage is 84.31373% with 24 lines in your changes missing coverage. Please review.

Project coverage is 74.07%. Comparing base (b8eb810) to head (cca5962).
Report is 288 commits behind head on main.

❗ Current head cca5962 differs from pull request most recent head 17f26be

Please upload reports for the commit 17f26be to get more accurate results.

Files	Patch %	Lines
...t/auth/oauth2/DefaultOAuth2AuthorizationGrant.java	42.30%	13 Missing and 2 partials ⚠️
...necorp/armeria/common/util/DefaultAsyncLoader.java	94.33%	2 Missing and 4 partials ⚠️
...necorp/armeria/common/util/AsyncLoaderBuilder.java	85.00%	3 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff              @@
##               main    #5590      +/-   ##
============================================
+ Coverage     73.95%   74.07%   +0.11%     
- Complexity    20115    21252    +1137     
============================================
  Files          1730     1848     +118     
  Lines         74161    78567    +4406     
  Branches       9465    10024     +559     
============================================
+ Hits          54847    58199    +3352     
- Misses        14837    15669     +832     
- Partials       4477     4699     +222     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[ikhoon]

Looks nice, @injae-kim! ❤️

Please address @minwoox comments.

[jrhee17]

Looks good in terms of correctness 👍 Thanks @injae-kim 🙇 👍 🙇

[minwoox]

Look great! Left a small suggestion. 👍

[minwoox]

What do you think of returing this.loadFuture here? If so we can remove the for loop and reduce accessing the volatile fields.

[minwoox]

This is what I've imagined:

@Override
public CompletableFuture<T> load() {
    final CompletableFuture<T> loadFuture = this.loadFuture;
    if (!loadFuture.isDone()) {
        // A load is in progress.
        return returnCacheOrFuture(cacheEntry, loadFuture);
    }

    final CacheEntry<T> cacheEntry = this.cacheEntry;
    final boolean isValid = isValid(cacheEntry);
    if (!isValid || needsRefresh(cacheEntry)) {
        final CompletableFuture<T> newFuture = new CompletableFuture<>();
        if (loadFutureUpdater.compareAndSet(this, loadFuture, newFuture)) {
            final T cache = cacheEntry != null ? cacheEntry.value : null;
            load(cache, newFuture);
            if (isValid) {
                logger.debug("Pre-fetching a new value. cache: {}, loader: {}", cache, loader);
                return UnmodifiableFuture.completedFuture(cache);
            }
            logger.debug("Loading a new value. cache: {}, loader: {}", cache, loader);
            return newFuture;
        }
        return returnCacheOrFuture(this.cacheEntry, this.loadFuture);
    } else {
        // The cache is still valid and no need to refresh.
        return returnCacheOrFuture(cacheEntry, loadFuture);
    }
}

private CompletableFuture<T> returnCacheOrFuture(@Nullable CacheEntry<T> cacheEntry,
                                                 CompletableFuture<T> loadFuture) {
    if (isValid(cacheEntry)) {
        return UnmodifiableFuture.completedFuture(cacheEntry.value);
    }
    return loadFuture;
}

[ikhoon]

It looks nicer.

[minwoox]

Looks great! Thanks a lot, @injae-kim and @ikhoon! 👍 👍 👍 👍 👍

[injae-kim]

@ikhoon really thank you for polishing PR & address comments 🙇 🙇

The code looks much simpler&nicer now!

[ikhoon]

@jrhee17 The code has been changed after your approval. I was wondering if you want to check the code again or if you already have done.

[ikhoon]

Gentle ping @trustin. The usage of obtrude*() has been removed. PTAL. 🙇‍♂️

[jrhee17]

I was wondering if you want to check the code again or if you already have done.

I think it should be fine to go ahead as I don't think the changes are in a critical path 👍