Define a Drain::flush method

This is simpler than the API in slog-rs#332 ,
but requires more work by slog_async to implement it.

Author: Techcable

src/lib.rs

@@ -1079,6 +1079,17 @@ where
         let _ = self.drain.log(record, &self.list);
     }
 
+    /// Flush all pending log records,
+    /// blocking until completion.
+    ///
+    /// Will call [`std::io::Write::flush`] if applicable.
+    ///
+    /// Returns [`FlushError::NotSupported`] if the underlying drain does not support [`Drain::flush`].
+    #[inline]
+    pub fn flush(&self) -> result::Result<(), FlushError> {
+        self.drain.flush()
+    }
+
     /// Get list of key-value pairs assigned to this `Logger`
     pub fn list(&self) -> &OwnedKVList {
         &self.list
@@ -1159,6 +1170,53 @@ where
     fn is_enabled(&self, level: Level) -> bool {
         self.drain.is_enabled(level)
     }
+
+    #[inline]
+    fn flush(&self) -> result::Result<(), FlushError> {
+        self.drain.flush()
+    }
+}
+
+/// An error that occurs when calling [`Drain::flush`].
+#[non_exhaustive]
+#[derive(Debug)]
+pub enum FlushError {
+    /// An error that occurs doing IO.
+    ///
+    /// Often triggered by [`std::io::]
+    #[cfg(feature = "std")]
+    Io(std::io::Error),
+    /// Indicates this drain does not support flushing.
+    NotSupported,
+}
+#[cfg(feature = "std")]
+impl From<std::io::Error> for FlushError {
+    fn from(value: std::io::Error) -> Self {
+        FlushError::Io(value)
+    }
+}
+#[cfg(has_std_error)]
+impl StdError for FlushError {
+    fn source(&self) -> Option<&(dyn StdError + 'static)> {
+        match self {
+            #[cfg(feature = "std")]
+            FlushError::Io(cause) => Some(cause),
+            FlushError::NotSupported => None,
+        }
+    }
+}
+impl fmt::Display for FlushError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            #[cfg(feature = "std")]
+            FlushError::Io(_) => {
+                f.write_str("Encountered IO error during flushing")
+            }
+            FlushError::NotSupported => {
+                f.write_str("Drain does not support flushing")
+            }
+        }
+    }
 }
 
 // {{{ Drain
@@ -1203,6 +1261,15 @@ pub trait Drain {
         values: &OwnedKVList,
     ) -> result::Result<Self::Ok, Self::Err>;
 
+    /// Flush all pending log records, blocking until completion.
+    ///
+    /// Should call [`std::io::Write::flush`] if applicable.
+    ///
+    /// Returns [`FlushError::NotSupported`] if the drain has not implemented this method.
+    fn flush(&self) -> result::Result<(), FlushError> {
+        Err(FlushError::NotSupported)
+    }
+
     /// **Avoid**: Check if messages at the specified log level are **maybe**
     /// enabled for this logger.
     ///
@@ -1365,6 +1432,10 @@ impl<'a, D: Drain + 'a> Drain for &'a D {
     fn is_enabled(&self, level: Level) -> bool {
         (**self).is_enabled(level)
     }
+    #[inline]
+    fn flush(&self) -> result::Result<(), FlushError> {
+        (**self).flush()
+    }
 }
 
 impl<'a, D: Drain + 'a> Drain for &'a mut D {
@@ -1382,6 +1453,10 @@ impl<'a, D: Drain + 'a> Drain for &'a mut D {
     fn is_enabled(&self, level: Level) -> bool {
         (**self).is_enabled(level)
     }
+    #[inline]
+    fn flush(&self) -> result::Result<(), FlushError> {
+        (**self).flush()
+    }
 }
 
 /// Internal utility module used to "maybe" bound traits
@@ -1543,6 +1618,10 @@ impl<D: Drain + ?Sized> Drain for Box<D> {
     fn is_enabled(&self, level: Level) -> bool {
         (**self).is_enabled(level)
     }
+    #[inline]
+    fn flush(&self) -> result::Result<(), FlushError> {
+        (**self).flush()
+    }
 }
 
 impl<D: Drain + ?Sized> Drain for Arc<D> {
@@ -1559,6 +1638,10 @@ impl<D: Drain + ?Sized> Drain for Arc<D> {
     fn is_enabled(&self, level: Level) -> bool {
         (**self).is_enabled(level)
     }
+    #[inline]
+    fn flush(&self) -> result::Result<(), FlushError> {
+        (**self).flush()
+    }
 }
 
 /// `Drain` discarding everything
@@ -1582,6 +1665,10 @@ impl Drain for Discard {
     fn is_enabled(&self, _level: Level) -> bool {
         false
     }
+    #[inline]
+    fn flush(&self) -> result::Result<(), FlushError> {
+        Ok(())
+    }
 }
 
 /// `Drain` filtering records
@@ -1630,6 +1717,10 @@ where
          */
         self.0.is_enabled(level)
     }
+    #[inline]
+    fn flush(&self) -> result::Result<(), FlushError> {
+        self.0.flush()
+    }
 }
 
 /// `Drain` filtering records by `Record` logging level
@@ -1670,6 +1761,10 @@ impl<D: Drain> Drain for LevelFilter<D> {
     fn is_enabled(&self, level: Level) -> bool {
         level.is_at_least(self.1) && self.0.is_enabled(level)
     }
+    #[inline]
+    fn flush(&self) -> result::Result<(), FlushError> {
+        self.0.flush()
+    }
 }
 
 /// `Drain` mapping error returned by another `Drain`
@@ -1711,6 +1806,10 @@ impl<D: Drain, E> Drain for MapError<D, E> {
     fn is_enabled(&self, level: Level) -> bool {
         self.drain.is_enabled(level)
     }
+    #[inline]
+    fn flush(&self) -> result::Result<(), FlushError> {
+        self.drain.flush()
+    }
 }
 
 /// `Drain` duplicating records into two other `Drain`s
@@ -1750,6 +1849,17 @@ impl<D1: Drain, D2: Drain> Drain for Duplicate<D1, D2> {
     fn is_enabled(&self, level: Level) -> bool {
         self.0.is_enabled(level) || self.1.is_enabled(level)
     }
+    /// Flush both drains.
+    ///
+    /// Will return [`FlushError::NotSupported`] if either drain does not support flushing.
+    /// If one drain supports flushing and the other does not,
+    /// it is unspecified whether or not anything will be flushed at all.
+    #[inline]
+    fn flush(&self) -> result::Result<(), FlushError> {
+        self.0.flush()?;
+        self.1.flush()?;
+        Ok(())
+    }
 }
 
 /// `Drain` panicking on error
@@ -1796,6 +1906,10 @@ where
     fn is_enabled(&self, level: Level) -> bool {
         self.0.is_enabled(level)
     }
+    #[inline]
+    fn flush(&self) -> result::Result<(), FlushError> {
+        self.0.flush()
+    }
 }
 
 /// `Drain` ignoring result
@@ -1832,6 +1946,11 @@ impl<D: Drain> Drain for IgnoreResult<D> {
     fn is_enabled(&self, level: Level) -> bool {
         self.drain.is_enabled(level)
     }
+
+    #[inline]
+    fn flush(&self) -> result::Result<(), FlushError> {
+        self.drain.flush()
+    }
 }
 
 /// Error returned by `Mutex<D : Drain>`
@@ -1927,6 +2046,13 @@ impl<D: Drain> Drain for std::sync::Mutex<D> {
     fn is_enabled(&self, level: Level) -> bool {
         self.lock().ok().map_or(true, |lock| lock.is_enabled(level))
     }
+    #[inline]
+    fn flush(&self) -> result::Result<(), FlushError> {
+        let guard = self.lock().map_err(|_poison| {
+            std::io::Error::new(std::io::ErrorKind::Other, "Mutex is poisoned")
+        })?;
+        guard.flush()
+    }
 }
 
 #[cfg(feature = "parking_lot_0_12")]