feat(s2n-quic-core): add platform event loop sleep event

common/docdiff/src/main.rs

@@ -79,14 +79,14 @@ impl fmt::Display for Dump {
 
 impl Dump {
     fn new(crate_name: &str) -> Result<Self> {
-        cmd!("cargo", "doc", "--all-features", "--workspace")
+        cmd!("cargo", "doc", "--all-features", "--workspace", "--target-dir", "target/docdiff")
             .env("RUSTFLAGS", "--cfg docdiff")
             .env("RUSTDOCFLAGS", "--cfg docdiff")
             .stdout_path("/dev/null")
             .run()?;
 
         let paths = glob(&format!(
-            "target/doc/{}/**/*.html",
+            "target/docdiff/doc/{}/**/*.html",
             crate_name.replace('-', "_")
         ))?
         .collect::<Vec<_>>();

quic/s2n-quic-core/src/event/generated.rs

@@ -880,6 +880,17 @@ pub mod api {
     }
     #[derive(Clone, Debug)]
     #[non_exhaustive]
+    pub struct PlatformEventLoopSleep {
+        #[doc = " The next time at which the event loop will wake"]
+        pub timeout: Option<core::time::Duration>,
+        #[doc = " The amount of time spent processing endpoint events in a single event loop"]
+        pub processing_duration: core::time::Duration,
+    }
+    impl Event for PlatformEventLoopSleep {
+        const NAME: &'static str = "platform:event_loop_sleep";
+    }
+    #[derive(Clone, Debug)]
+    #[non_exhaustive]
     pub enum PlatformFeatureConfiguration {
         #[non_exhaustive]
         #[doc = " Emitted when segment offload was configured"]
@@ -1870,6 +1881,22 @@ pub mod tracing {
             } = event;
             tracing :: event ! (target : "platform_event_loop_wakeup" , parent : parent , tracing :: Level :: DEBUG , timeout_expired = tracing :: field :: debug (timeout_expired) , rx_ready = tracing :: field :: debug (rx_ready) , tx_ready = tracing :: field :: debug (tx_ready) , application_wakeup = tracing :: field :: debug (application_wakeup));
         }
+        #[inline]
+        fn on_platform_event_loop_sleep(
+            &mut self,
+            meta: &api::EndpointMeta,
+            event: &api::PlatformEventLoopSleep,
+        ) {
+            let parent = match meta.endpoint_type {
+                api::EndpointType::Client {} => self.client.id(),
+                api::EndpointType::Server {} => self.server.id(),
+            };
+            let api::PlatformEventLoopSleep {
+                timeout,
+                processing_duration,
+            } = event;
+            tracing :: event ! (target : "platform_event_loop_sleep" , parent : parent , tracing :: Level :: DEBUG , timeout = tracing :: field :: debug (timeout) , processing_duration = tracing :: field :: debug (processing_duration));
+        }
     }
 }
 pub mod builder {
@@ -3399,6 +3426,26 @@ pub mod builder {
         }
     }
     #[derive(Clone, Debug)]
+    pub struct PlatformEventLoopSleep {
+        #[doc = " The next time at which the event loop will wake"]
+        pub timeout: Option<core::time::Duration>,
+        #[doc = " The amount of time spent processing endpoint events in a single event loop"]
+        pub processing_duration: core::time::Duration,
+    }
+    impl IntoEvent<api::PlatformEventLoopSleep> for PlatformEventLoopSleep {
+        #[inline]
+        fn into_event(self) -> api::PlatformEventLoopSleep {
+            let PlatformEventLoopSleep {
+                timeout,
+                processing_duration,
+            } = self;
+            api::PlatformEventLoopSleep {
+                timeout: timeout.into_event(),
+                processing_duration: processing_duration.into_event(),
+            }
+        }
+    }
+    #[derive(Clone, Debug)]
     pub enum PlatformFeatureConfiguration {
         #[doc = " Emitted when segment offload was configured"]
         Gso {
@@ -4091,6 +4138,16 @@ mod traits {
             let _ = meta;
             let _ = event;
         }
+        #[doc = "Called when the `PlatformEventLoopSleep` event is triggered"]
+        #[inline]
+        fn on_platform_event_loop_sleep(
+            &mut self,
+            meta: &EndpointMeta,
+            event: &PlatformEventLoopSleep,
+        ) {
+            let _ = meta;
+            let _ = event;
+        }
         #[doc = r" Called for each event that relates to the endpoint and all connections"]
         #[inline]
         fn on_event<M: Meta, E: Event>(&mut self, meta: &M, event: &E) {
@@ -4599,6 +4656,15 @@ mod traits {
             (self.1).on_platform_event_loop_wakeup(meta, event);
         }
         #[inline]
+        fn on_platform_event_loop_sleep(
+            &mut self,
+            meta: &EndpointMeta,
+            event: &PlatformEventLoopSleep,
+        ) {
+            (self.0).on_platform_event_loop_sleep(meta, event);
+            (self.1).on_platform_event_loop_sleep(meta, event);
+        }
+        #[inline]
         fn on_event<M: Meta, E: Event>(&mut self, meta: &M, event: &E) {
             self.0.on_event(meta, event);
             self.1.on_event(meta, event);
@@ -4664,6 +4730,8 @@ mod traits {
         fn on_platform_feature_configured(&mut self, event: builder::PlatformFeatureConfigured);
         #[doc = "Publishes a `PlatformEventLoopWakeup` event to the publisher's subscriber"]
         fn on_platform_event_loop_wakeup(&mut self, event: builder::PlatformEventLoopWakeup);
+        #[doc = "Publishes a `PlatformEventLoopSleep` event to the publisher's subscriber"]
+        fn on_platform_event_loop_sleep(&mut self, event: builder::PlatformEventLoopSleep);
         #[doc = r" Returns the QUIC version, if any"]
         fn quic_version(&self) -> Option<u32>;
     }
@@ -4784,6 +4852,13 @@ mod traits {
             self.subscriber.on_event(&self.meta, &event);
         }
         #[inline]
+        fn on_platform_event_loop_sleep(&mut self, event: builder::PlatformEventLoopSleep) {
+            let event = event.into_event();
+            self.subscriber
+                .on_platform_event_loop_sleep(&self.meta, &event);
+            self.subscriber.on_event(&self.meta, &event);
+        }
+        #[inline]
         fn quic_version(&self) -> Option<u32> {
             self.quic_version
         }
@@ -5248,6 +5323,7 @@ pub mod testing {
         pub platform_rx_error: u32,
         pub platform_feature_configured: u32,
         pub platform_event_loop_wakeup: u32,
+        pub platform_event_loop_sleep: u32,
     }
     impl Drop for Subscriber {
         fn drop(&mut self) {
@@ -5317,6 +5393,7 @@ pub mod testing {
                 platform_rx_error: 0,
                 platform_feature_configured: 0,
                 platform_event_loop_wakeup: 0,
+                platform_event_loop_sleep: 0,
             }
         }
     }
@@ -5768,6 +5845,14 @@ pub mod testing {
             self.platform_event_loop_wakeup += 1;
             self.output.push(format!("{:?} {:?}", meta, event));
         }
+        fn on_platform_event_loop_sleep(
+            &mut self,
+            meta: &api::EndpointMeta,
+            event: &api::PlatformEventLoopSleep,
+        ) {
+            self.platform_event_loop_sleep += 1;
+            self.output.push(format!("{:?} {:?}", meta, event));
+        }
     }
     #[derive(Clone, Debug)]
     pub struct Publisher {
@@ -5818,6 +5903,7 @@ pub mod testing {
         pub platform_rx_error: u32,
         pub platform_feature_configured: u32,
         pub platform_event_loop_wakeup: u32,
+        pub platform_event_loop_sleep: u32,
     }
     impl Publisher {
         #[doc = r" Creates a publisher with snapshot assertions enabled"]
@@ -5877,6 +5963,7 @@ pub mod testing {
                 platform_rx_error: 0,
                 platform_feature_configured: 0,
                 platform_event_loop_wakeup: 0,
+                platform_event_loop_sleep: 0,
             }
         }
     }
@@ -5949,6 +6036,11 @@ pub mod testing {
             let event = event.into_event();
             self.output.push(format!("{:?}", event));
         }
+        fn on_platform_event_loop_sleep(&mut self, event: builder::PlatformEventLoopSleep) {
+            self.platform_event_loop_sleep += 1;
+            let event = event.into_event();
+            self.output.push(format!("{:?}", event));
+        }
         fn quic_version(&self) -> Option<u32> {
             Some(1)
         }

quic/s2n-quic-events/events/platform.rs

@@ -76,3 +76,12 @@ struct PlatformEventLoopWakeup {
     tx_ready: bool,
     application_wakeup: bool,
 }
+
+#[event("platform:event_loop_sleep")]
+#[subject(endpoint)]
+struct PlatformEventLoopSleep {
+    /// The next time at which the event loop will wake
+    timeout: Option<core::time::Duration>,
+    /// The amount of time spent processing endpoint events in a single event loop
+    processing_duration: core::time::Duration,
+}

quic/s2n-quic-platform/src/io/tokio.rs

@@ -523,11 +523,12 @@ impl<E: Endpoint<PathHandle = PathHandle>> Instance<E> {
                 return Ok(());
             };
 
+            let wakeup_timestamp = clock.get_time();
             let subscriber = endpoint.subscriber();
             let mut publisher = event::EndpointPublisherSubscriber::new(
                 event::builder::EndpointMeta {
                     endpoint_type: E::ENDPOINT_TYPE,
-                    timestamp: clock.get_time(),
+                    timestamp: wakeup_timestamp,
                 },
                 None,
                 subscriber,
@@ -555,9 +556,29 @@ impl<E: Endpoint<PathHandle = PathHandle>> Instance<E> {
 
             endpoint.transmit(&mut tx.tx_queue(), &clock);
 
-            if let Some(delay) = endpoint.timeout() {
-                timer.update(delay);
+            let timeout = endpoint.timeout();
+
+            if let Some(timeout) = timeout {
+                timer.update(timeout);
             }
+
+            let timestamp = clock.get_time();
+            let subscriber = endpoint.subscriber();
+            let mut publisher = event::EndpointPublisherSubscriber::new(
+                event::builder::EndpointMeta {
+                    endpoint_type: E::ENDPOINT_TYPE,
+                    timestamp,
+                },
+                None,
+                subscriber,
+            );
+
+            // notify the application that we're going to sleep
+            let timeout = timeout.map(|t| t.saturating_duration_since(timestamp));
+            publisher.on_platform_event_loop_sleep(event::builder::PlatformEventLoopSleep {
+                timeout,
+                processing_duration: timestamp.saturating_duration_since(wakeup_timestamp),
+            });
         }
     }
 }

quic/s2n-quic/api.snap

@@ -2118,6 +2118,9 @@ module s2n_quic::provider::event::events exports struct:
 module s2n_quic::provider::event::events exports struct:
   s2n_quic::provider::event::events::PathCreated
 
+module s2n_quic::provider::event::events exports struct:
+  s2n_quic::provider::event::events::PlatformEventLoopSleep
+
 module s2n_quic::provider::event::events exports struct:
   s2n_quic::provider::event::events::PlatformEventLoopWakeup
 
@@ -4302,6 +4305,41 @@ struct s2n_quic::provider::event::events::PathCreated exports field:
 struct s2n_quic::provider::event::events::PathCreated exports constant:
   pub const NAME: &'static str
 
+struct s2n_quic::provider::event::events::PlatformEventLoopSleep is non-exhaustive
+
+struct s2n_quic::provider::event::events::PlatformEventLoopSleep implements trait:
+  impl core::clone::Clone for s2n_quic::provider::event::events::PlatformEventLoopSleep
+
+struct s2n_quic::provider::event::events::PlatformEventLoopSleep implements trait:
+  impl core::fmt::Debug for s2n_quic::provider::event::events::PlatformEventLoopSleep
+
+struct s2n_quic::provider::event::events::PlatformEventLoopSleep implements trait:
+  impl core::marker::Send for s2n_quic::provider::event::events::PlatformEventLoopSleep
+
+struct s2n_quic::provider::event::events::PlatformEventLoopSleep implements trait:
+  impl core::marker::Sync for s2n_quic::provider::event::events::PlatformEventLoopSleep
+
+struct s2n_quic::provider::event::events::PlatformEventLoopSleep implements trait:
+  impl core::marker::Unpin for s2n_quic::provider::event::events::PlatformEventLoopSleep
+
+struct s2n_quic::provider::event::events::PlatformEventLoopSleep implements trait:
+  impl s2n_quic::provider::event::Event for s2n_quic::provider::event::events::PlatformEventLoopSleep
+
+struct s2n_quic::provider::event::events::PlatformEventLoopSleep implements trait:
+  impl std::panic::RefUnwindSafe for s2n_quic::provider::event::events::PlatformEventLoopSleep
+
+struct s2n_quic::provider::event::events::PlatformEventLoopSleep implements trait:
+  impl std::panic::UnwindSafe for s2n_quic::provider::event::events::PlatformEventLoopSleep
+
+struct s2n_quic::provider::event::events::PlatformEventLoopSleep exports field:
+  processing_duration: core::time::Duration
+
+struct s2n_quic::provider::event::events::PlatformEventLoopSleep exports constant:
+  pub const NAME: &'static str
+
+struct s2n_quic::provider::event::events::PlatformEventLoopSleep exports field:
+  timeout: core::option::Option<core::time::Duration>
+
 struct s2n_quic::provider::event::events::PlatformEventLoopWakeup is non-exhaustive
 
 struct s2n_quic::provider::event::events::PlatformEventLoopWakeup exports field: