1# gRPC EventEngine 2 3An EventEngine handles all cross-platform I/O, task execution, and DNS 4resolution for gRPC. A default, cross-platform implementation is provided with 5gRPC, but part of the intent here is to provide an interface for external 6integrators to bring their own functionality. This allows for integration with 7external event loops, siloing I/O and task execution between channels or 8servers, and other custom integrations that were previously unsupported. 9 10*WARNING*: This is experimental code and is subject to change. 11 12## High level expectations of an EventEngine implementation 13 14### Provide their own I/O threads 15EventEngines are expected to internally create whatever threads are required to 16perform I/O and execute callbacks. For example, an EventEngine implementation 17may want to spawn separate thread pools for polling and callback execution. 18 19### Provisioning data buffers via Slice allocation 20At a high level, gRPC provides a `ResourceQuota` system that allows gRPC to 21reclaim memory and degrade gracefully when memory reaches application-defined 22thresholds. To enable this feature, the memory allocation of read/write buffers 23within an EventEngine must be acquired in the form of Slices from 24SliceAllocators. This is covered more fully in the gRFC and code. 25 26### Documentating expectations around callback execution 27Some callbacks may be expensive to run. EventEngines should decide on and 28document whether callback execution might block polling operations. This way, 29application developers can plan accordingly (e.g., run their expensive callbacks 30on a separate thread if necessary). 31 32### Handling concurrent usage 33Assume that gRPC may use an EventEngine concurrently across multiple threads. 34 35## TODO: documentation 36 37* Example usage 38* Link to gRFC 39