Skip to content

AGENTS.md

Latest commit

 

History

History
120 lines (105 loc) · 5.51 KB

AGENTS.md

File metadata and controls

120 lines (105 loc) · 5.51 KB
Raw

gRPC Core Call

This directory is the heart of the gRPC C++ core, defining the fundamental data structures and mechanisms for representing and managing a single RPC.

See also: gRPC Core overview

Overarching Purpose

The code in this directory provides the client and server-side representations of a call, the central "spine" that connects them, and the various components needed to manage the lifecycle of an RPC, including metadata, messages, and status.

Core Concepts

  • CallSpine: The CallSpine is the central component of a gRPC call. It encapsulates the call's context, including the arena allocator, call filters, and the pipes for message and metadata communication. The CallSpine is shared between a CallInitiator (the client-side) and a CallHandler (the server-side).
  • CallInitiator: The CallInitiator is the client-side view of a call. It is used for initiating requests and receiving responses.
  • CallHandler: The CallHandler is the server-side view of a call. It is used for handling incoming requests and sending responses.
  • ClientCall: The ClientCall is the public client-side API for a call. It wraps the CallInitiator and CallSpine.
  • ServerCall: The ServerCall is the public server-side API for a call. It wraps the CallHandler and CallSpine.

Differentiating Call V1 and Call V3 Code

  • Implementation Class: The classes used to represent the call interface.
  • Concurrency Model: Concurrency and thread safety mechanism.
  • Companion Transports: Transport layers compatible with each stack.
  • Creation Method: The entry point used to instantiate new calls.
    • Call V1: grpc_call_create
    • Call V3: MakeClientCall and MakeServerCall
  • Exclusive Files: C++ source files exclusive to each stack model.
    • Call V1:
      • src/core/lib/surface/filter_stack_call.{h,cc}
      • src/core/lib/surface/legacy_channel.{h,cc}
      • src/core/lib/channel/channel_stack.{h,cc}
      • src/core/lib/channel/channel_stack_builder.{h,cc}
      • src/core/ext/filters/channel_idle/legacy_channel_idle_filter.cc
    • Call V3:
      • src/core/call/client_call.{h,cc}
      • src/core/call/server_call.{h,cc}
      • src/core/call/call_spine.{h,cc}
      • src/core/call/call_filters.{h,cc}
      • src/core/client_channel/direct_channel.{h,cc}
  • Shared Files: Source files used by both Call V1 and Call V3.
    • src/core/lib/surface/call.{h,cc}
    • src/core/lib/surface/call_utils.{h,cc}
    • src/core/call/metadata.{h,cc}
    • src/core/call/metadata_batch.{h,cc}

Call V3 Stack

Call V3 Stack

  • src/core/call/call_spine.{h,cc}: The CallSpine is the key abstraction to understand in this directory. It's the "glue" that holds a call together.
  • The use of CallInitiator and CallHandler provides a clean separation of concerns between the client and server sides of a call.
  • In a CallSpine we always have a CallInitiator and CallHandler pair.
  • CallInitiator is always near/towards the client side.
  • CallHandler is always near/towards the server side.
  • When CallInitiator sends metadata, it flows into the spine. The spine executes filter hooks before reaching CallHandler.
  • Similarly, response metadata and messages from CallHandler pass through filters and reach the CallInitiator.

Files

  • src/core/call/client_call.{h,cc}: These files define the ClientCall class.
  • src/core/call/server_call.{h,cc}: These files define the ServerCall class.
  • src/core/call/metadata.{h,cc}, src/core/call/metadata_batch.{h,cc}: These files provide the data structures for representing and manipulating RPC metadata.
  • src/core/call/message.{h,cc}: Defines the Message class, which is a container for RPC messages.
  • src/core/call/call_filters.{h,cc}: These files define the CallFilters class, which is responsible for managing the filters for a call.
  • src/core/call/interception_chain.{h,cc}: These files define the InterceptionChain class, which is used to manage the execution of a set of interceptors.

Notes

  • This directory is heavily based on the gRPC Core Promise API. Familiarity with that API is essential for understanding the code here.
  • The CallFilters class is responsible for managing the filters for a call. See the channel documentation for more information about filters.