AGENTS.md

1# EventEngine
2 
3This directory contains the implementation of the gRPC EventEngine.
4 
5## Overarching Purpose
6 
7The EventEngine is an abstraction layer that provides a consistent interface to the underlying operating system's I/O and threading primitives. It is used by gRPC to perform asynchronous I/O, schedule tasks, and resolve DNS names.
8 
9## Files
10 
11*   `event_engine.h`: The public interface to the EventEngine. This file is not located in this directory, but in `include/grpc/event_engine/`.
12*   `default_event_engine_factory.h`, `default_event_engine_factory.cc`: These files provide the default, cross-platform implementation of the EventEngine.
13*   `posix_engine`, `windows`, `cf_engine`: These directories contain the platform-specific implementations of the EventEngine.
14 
15## Major Classes
16 
17*   `grpc_event_engine::experimental::EventEngine`: The abstract base class for an EventEngine.
18*   `grpc_event_engine::experimental::EventEngine::Endpoint`: Represents one end of a connection.
19*   `grpc_event_engine::experimental::EventEngine::Listener`: Used to accept incoming connections.
20*   `grpc_event_engine::experimental::EventEngine::DNSResolver`: Used to resolve DNS names.
21 
22## Notes
23 
24*   The EventEngine is a key component of gRPC's performance and portability. It allows gRPC to be easily ported to new platforms and to take advantage of the latest I/O and threading features.
25*   Applications can provide their own implementation of the EventEngine by calling `SetEventEngineFactory`. This can be useful for integrating gRPC with an existing event loop or for using a custom network stack.
26*   The EventEngine is a low-level component of the gRPC stack. Most application developers will not need to interact with it directly.
27 
28## See also
29 
30*   `src/core/lib/iomgr/AGENTS.md`
31    *   The EventEngine is replacing the `iomgr` subsystem.
32