Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Avoid giving the result of loads a non-null type. #1805

Merged
merged 6 commits into from
Dec 5, 2024
Merged

Avoid giving the result of loads a non-null type. #1805

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
41d97e6
Avoid giving the result of loads a non-null type.
cpovirk Dec 3, 2024
e9e5013
Make function output types nullable instead of unspecified.
cpovirk Dec 3, 2024
7b93d04
Leave the value type of the `CompletableFuture` in `asMap` unspecified.
cpovirk Dec 3, 2024
1b767fb
Allow async loads to return `null`.
cpovirk Dec 3, 2024
bc74eb6
Undo accidental Javadoc formatting.
cpovirk Dec 3, 2024
d9235d3
Unmark `*LoadingCache` result types.
cpovirk Dec 4, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 26 additions & 14 deletions caffeine/src/main/java/com/github/benmanes/caffeine/cache/AsyncCache.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,9 @@
import java.util.function.BiFunction;
import java.util.function.Function;

import org.jspecify.annotations.NonNull;
import org.jspecify.annotations.NullMarked;
import org.jspecify.annotations.NullUnmarked;
import org.jspecify.annotations.Nullable;

/**
Expand All @@ -47,7 +49,7 @@ public interface AsyncCache<K, V> {
*
* @param key the key whose associated value is to be returned
* @return the future value to which the specified key is mapped, or {@code null} if this cache
* does not contain a mapping for the key
* does not contain a mapping for the key
* @throws NullPointerException if the specified key is null
*/
@Nullable
Expand All @@ -71,7 +73,9 @@ public interface AsyncCache<K, V> {
* @return the current (existing or computed) future value associated with the specified key
* @throws NullPointerException if the specified key or mappingFunction is null
*/
CompletableFuture<V> get(K key, Function<? super K, ? extends V> mappingFunction);
@NullUnmarked
@NonNull CompletableFuture<V> get(
@NonNull K key, @NonNull Function<? super @NonNull K, ? extends @Nullable V> mappingFunction);

/**
* Returns the future associated with the {@code key} in this cache, obtaining that value from
Expand All @@ -89,15 +93,22 @@ public interface AsyncCache<K, V> {
*
* @param key the key with which the specified value is to be associated
* @param mappingFunction the function to asynchronously compute a value, optionally using the
* given executor
* given executor
* @return the current (existing or computed) future value associated with the specified key
* @throws NullPointerException if the specified key or mappingFunction is null, or if the
* future returned by the mappingFunction is null
* @throws RuntimeException or Error if the mappingFunction does when constructing the future,
* in which case the mapping is left unestablished
*/
CompletableFuture<V> get(K key, BiFunction<? super K, ? super Executor,
? extends CompletableFuture<? extends V>> mappingFunction);
@NullUnmarked
@NonNull CompletableFuture<V> get(
@NonNull K key,
@NonNull
BiFunction<
? super @NonNull K,
? super @NonNull Executor,
? extends @NonNull CompletableFuture<? extends @Nullable V>>
mappingFunction);

/**
* Returns the future of a map of the values associated with the {@code keys}, creating or
Expand All @@ -118,11 +129,11 @@ CompletableFuture<V> get(K key, BiFunction<? super K, ? super Executor,
* @param keys the keys whose associated values are to be returned
* @param mappingFunction the function to asynchronously compute the values
* @return a future containing an unmodifiable mapping of keys to values for the specified keys in
* this cache
* this cache
* @throws NullPointerException if the specified collection is null or contains a null element, or
* if the future returned by the mappingFunction is null
* if the future returned by the mappingFunction is null
* @throws RuntimeException or Error if the mappingFunction does so, in which case the mapping is
* left unestablished
* left unestablished
*/
CompletableFuture<Map<K, V>> getAll(Iterable<? extends K> keys,
Function<? super Set<? extends K>, ? extends Map<? extends K, ? extends V>> mappingFunction);
Expand All @@ -146,13 +157,13 @@ CompletableFuture<Map<K, V>> getAll(Iterable<? extends K> keys,
*
* @param keys the keys whose associated values are to be returned
* @param mappingFunction the function to asynchronously compute the values, optionally using the
* given executor
* given executor
* @return a future containing an unmodifiable mapping of keys to values for the specified keys in
* this cache
* this cache
* @throws NullPointerException if the specified collection is null or contains a null element, or
* if the future returned by the mappingFunction is null
* if the future returned by the mappingFunction is null
* @throws RuntimeException or Error if the mappingFunction does so, in which case the mapping is
* left unestablished
* left unestablished
*/
CompletableFuture<Map<K, V>> getAll(Iterable<? extends K> keys,
BiFunction<? super Set<? extends K>, ? super Executor,
Expand All @@ -170,7 +181,7 @@ CompletableFuture<Map<K, V>> getAll(Iterable<? extends K> keys,
* @param valueFuture the value to be associated with the specified key
* @throws NullPointerException if the specified key or value is null
*/
void put(K key, CompletableFuture<? extends V> valueFuture);
void put(K key, CompletableFuture<? extends @Nullable V> valueFuture);
cpovirk marked this conversation as resolved.
Show resolved Hide resolved

/**
* Returns a view of the entries stored in this cache as a thread-safe map. Modifications made to
cpovirk marked this conversation as resolved.
Show resolved Hide resolved
Expand All @@ -187,7 +198,8 @@ CompletableFuture<Map<K, V>> getAll(Iterable<? extends K> keys,
*
* @return a thread-safe view of this cache supporting all of the optional {@link Map} operations
*/
ConcurrentMap<K, CompletableFuture<V>> asMap();
@NullUnmarked
@NonNull ConcurrentMap<@NonNull K, @NonNull CompletableFuture<V>> asMap();

/**
* Returns a view of the entries stored in this cache as a synchronous {@link Cache}. A mapping is
Expand Down
19 changes: 11 additions & 8 deletions caffeine/src/main/java/com/github/benmanes/caffeine/cache/Cache.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,9 @@
import java.util.concurrent.ConcurrentMap;
import java.util.function.Function;

import org.jspecify.annotations.NonNull;
import org.jspecify.annotations.NullMarked;
import org.jspecify.annotations.NullUnmarked;
import org.jspecify.annotations.Nullable;

import com.github.benmanes.caffeine.cache.stats.CacheStats;
Expand All @@ -46,7 +48,7 @@ public interface Cache<K, V> {
*
* @param key the key whose associated value is to be returned
* @return the value to which the specified key is mapped, or {@code null} if this cache does not
* contain a mapping for the key
* contain a mapping for the key
* @throws NullPointerException if the specified key is null
*/
@Nullable
Expand All @@ -70,14 +72,15 @@ public interface Cache<K, V> {
* @param key the key with which the specified value is to be associated
* @param mappingFunction the function to compute a value
* @return the current (existing or computed) value associated with the specified key, or null if
* the computed value is null
* the computed value is null
* @throws NullPointerException if the specified key or mappingFunction is null
* @throws IllegalStateException if the computation detectably attempts a recursive update to this
* cache that would otherwise never complete
* cache that would otherwise never complete
* @throws RuntimeException or Error if the mappingFunction does so, in which case the mapping is
* left unestablished
* left unestablished
*/
V get(K key, Function<? super K, ? extends V> mappingFunction);
@NullUnmarked
V get(@NonNull K key, Function<? super @NonNull K, ? extends @Nullable V> mappingFunction);

/**
* Returns a map of the values associated with the {@code keys} in this cache. The returned map
Expand Down Expand Up @@ -114,9 +117,9 @@ public interface Cache<K, V> {
* @param mappingFunction the function to compute the values
* @return an unmodifiable mapping of keys to values for the specified keys in this cache
* @throws NullPointerException if the specified collection is null or contains a null element, or
* if the map returned by the mappingFunction is null
* if the map returned by the mappingFunction is null
* @throws RuntimeException or Error if the mappingFunction does so, in which case the mapping is
* left unestablished
* left unestablished
*/
Map<K, V> getAll(Iterable<? extends K> keys,
Function<? super Set<? extends K>, ? extends Map<? extends K, ? extends V>> mappingFunction);
Expand All @@ -143,7 +146,7 @@ Map<K, V> getAll(Iterable<? extends K> keys,
*
* @param map the mappings to be stored in this cache
* @throws NullPointerException if the specified map is null or the specified map contains null
* keys or values
* keys or values
*/
void putAll(Map<? extends K, ? extends V> map);

Expand Down
Loading