or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

cancellation-system.mdcontext-management.mddeadline-management.mdexecution-utilities.mdindex.md
tile.json

tessl/maven-io-grpc--grpc-context

Context propagation mechanism for Java applications that enables carrying scoped values across API boundaries and between threads

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/io.grpc/grpc-context@1.73.x

To install, run

npx @tessl/cli install tessl/maven-io-grpc--grpc-context@1.73.0

index.mddocs/

gRPC Context

gRPC Context is a Java library that provides a context propagation mechanism for carrying scoped values across API boundaries and between threads. It enables secure transmission of security principals, credentials, and distributed tracing information through immutable Context objects with automatic inheritance, cancellation propagation, and timeout-based automatic cancellation.

Package Information

  • Package Name: io.grpc:grpc-context
  • Package Type: Maven
  • Language: Java
  • Installation: 
    <dependency>
  <groupId>io.grpc</groupId>
  <artifactId>grpc-context</artifactId>
  <version>1.73.0</version>
</dependency>

Core Imports

import io.grpc.Context;
import io.grpc.Deadline;

Basic Usage

import io.grpc.Context;
import java.util.concurrent.TimeUnit;

// Create a context key
Context.Key<String> USER_ID_KEY = Context.key("userId");

// Set a value in the current context
Context withUser = Context.current().withValue(USER_ID_KEY, "user123");

// Run code within the context scope
withUser.run(() -> {
    String userId = USER_ID_KEY.get(); // "user123"
    processUserRequest(userId);
});

// Create a cancellable context with timeout
try (Context.CancellableContext withTimeout = Context.current()
        .withDeadlineAfter(5, TimeUnit.SECONDS, scheduler)) {
    
    Context toRestore = withTimeout.attach();
    try {
        // Long-running operation that will be cancelled after 5 seconds
        performLongRunningTask();
    } finally {
        withTimeout.detach(toRestore);
    }
}

Architecture

gRPC Context is built around several key components:

  • Context Objects: Immutable containers for scoped values that inherit from parent contexts
  • Storage System: Pluggable storage mechanism with default ThreadLocal-based implementation
  • Key System: Type-safe keys using reference equality for accessing context values
  • Cancellation Framework: Hierarchical cancellation with listener notification and cause tracking
  • Deadline Management: Absolute time-based automatic cancellation with timeout conversion
  • Execution Wrapping: Utilities to propagate context across thread boundaries and async operations

Capabilities

Context Management

Core context creation, attachment, and value propagation functionality. Essential for maintaining scoped state across API boundaries and thread switches.

public static final Context ROOT;
public static Context current();
public static <T> Context.Key<T> key(String debugString);
public static <T> Context.Key<T> keyWithDefault(String debugString, T defaultValue);

public <V> Context withValue(Context.Key<V> key, V value);
public Context fork();
public Context attach();
public void detach(Context toAttach);

Context Management

Cancellation System

Cancellable contexts with hierarchical cancellation propagation, listener notification, and cause tracking for managing the lifecycle of operations.

public Context.CancellableContext withCancellation();
public boolean isCancelled();
public Throwable cancellationCause();
public void addListener(Context.CancellationListener listener, Executor executor);

public interface CancellationListener {
    void cancelled(Context context);
}

public static final class CancellableContext extends Context implements Closeable {
    public boolean cancel(Throwable cause);
    public void close();
}

Cancellation System

Deadline Management

Absolute time-based deadline management with automatic cancellation and timeout conversion capabilities for time-bounded operations.

public Context.CancellableContext withDeadline(Deadline deadline, ScheduledExecutorService scheduler);
public Context.CancellableContext withDeadlineAfter(long duration, TimeUnit unit, ScheduledExecutorService scheduler);
public Deadline getDeadline();

public static Deadline after(long duration, TimeUnit units);
public boolean isExpired();
public long timeRemaining(TimeUnit unit);

Deadline Management

Execution Utilities

Utilities for wrapping Runnables, Callables, and Executors to automatically propagate context across thread boundaries and asynchronous operations.

public void run(Runnable r);
public <V> V call(Callable<V> c) throws Exception;
public Runnable wrap(Runnable r);
public <C> Callable<C> wrap(Callable<C> c);
public Executor fixedContextExecutor(Executor e);
public static Executor currentContextExecutor(Executor e);

Execution Utilities

Types

public static final class Key<T> {
    public T get();
    public T get(Context context);
    public String toString();
}

public abstract static class Storage {
    public abstract Context doAttach(Context toAttach);
    public abstract void detach(Context toDetach, Context toRestore);
    public abstract Context current();
}

public abstract static class Ticker {
    public abstract long nanoTime();
}