Skip to content

Commit

Permalink
context: Add docs describing common Key usage
Browse files Browse the repository at this point in the history
This recently came up in https://stackoverflow.com/a/67062503/4690866,
but it has come up multiple times before. These docs aren't ideal, as
they may be missed by a reader and so references in other parts of the
API would probably be appropriate. There could also be something about
"Context is not a general purpose map." But this is an improvement, and
I didn't want to let the perfect be the enemy of the good.
  • Loading branch information
ejona86 committed Apr 16, 2021
1 parent 4ad4926 commit 384f4c4
Showing 1 changed file with 6 additions and 1 deletion.
7 changes: 6 additions & 1 deletion context/src/main/java/io/grpc/Context.java
Expand Up @@ -955,7 +955,12 @@ public interface CancellationListener {
}

/**
* Key for indexing values stored in a context.
* Key for indexing values stored in a context. Keys use reference equality and Context does not
* provide a mechanism to loop over Keys. This means there is no way to access a Key's value from
* a Context without having access to the Key instance itself. This allows strong control over
* what code can get/set a key in the Context. For example, you might manage access to Key similar
* to a ThreadLocal using Java visibility (private/protected). Generally Keys are stored in static
* fields.
*/
public static final class Key<T> {
private final String name;
Expand Down

0 comments on commit 384f4c4

Please sign in to comment.