1 // Copyright 2022 gRPC authors.
2 //
3 // Licensed under the Apache License, Version 2.0 (the "License");
4 // you may not use this file except in compliance with the License.
5 // You may obtain a copy of the License at
6 //
7 //     http://www.apache.org/licenses/LICENSE-2.0
8 //
9 // Unless required by applicable law or agreed to in writing, software
10 // distributed under the License is distributed on an "AS IS" BASIS,
11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 // See the License for the specific language governing permissions and
13 // limitations under the License.
14 #ifndef GRPC_SRC_CORE_LIB_EVENT_ENGINE_POLLER_H
15 #define GRPC_SRC_CORE_LIB_EVENT_ENGINE_POLLER_H
16 
17 #include <grpc/support/port_platform.h>
18 
19 #include "absl/functional/function_ref.h"
20 
21 #include <grpc/event_engine/event_engine.h>
22 
23 namespace grpc_event_engine {
24 namespace experimental {
25 
26 // A generic cross-platform "poller" concept.
27 // Concrete implementations will likely manage a set of sockets/file
28 // descriptors/etc, allowing threads to drive polling and event processing via
29 // Work(...).
30 class Poller {
31  public:
32   enum class WorkResult { kOk, kDeadlineExceeded, kKicked };
33 
34   virtual ~Poller() = default;
35   // Poll once for events and process received events. The callback function
36   // "schedule_poll_again" is expected to be run synchronously prior to
37   // processing received events. The callback's responsibility primarily is to
38   // schedule Poller::Work asynchronously again. This would ensure that the next
39   // polling cycle would run as quickly as possible to ensure continuous
40   // polling.
41   //
42   // Returns:
43   //  * Poller::WorkResult::kKicked if it was Kicked. A poller that was Kicked
44   //  may still process some events and if so, it may have run the
45   //  schedule_poll_again callback function synchronously. When the poller
46   //  returns Poller::WorkResult::kKicked it's up to the user to determine
47   //  if the schedule_poll_again callback has run or not.
48   //  * Poller::WorkResult::kDeadlineExceeded if timeout occurred. The
49   //  schedule_poll_again callback is not run in this case.
50   //  * Poller::WorkResult::kOk, otherwise indicating that the
51   //  schedule_poll_again callback function was run synchronously before some
52   //  events were processed.
53   virtual WorkResult Work(EventEngine::Duration timeout,
54                           absl::FunctionRef<void()> schedule_poll_again) = 0;
55   // Trigger the threads executing Work(..) to break out as soon as possible.
56   virtual void Kick() = 0;
57 };
58 
59 }  // namespace experimental
60 }  // namespace grpc_event_engine
61 
62 #endif  // GRPC_SRC_CORE_LIB_EVENT_ENGINE_POLLER_H
63