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