Add yet another Buffer error message example. (#1375)

Add the error message described [here], and a workaround.

[here]: #1290 (comment)

Author: sunfishcode

examples/buffer_errors.rs

@@ -6,6 +6,7 @@
 fn main() {
     error_buffer_wrapper();
     error_retry_closure();
+    error_retry_closure_uninit();
     error_retry_indirect_closure();
     error_empty_slice();
     error_array_by_value();
@@ -40,8 +41,8 @@ fn error_retry_closure() {
     use rustix::io;
     use rustix::io::retry_on_intr;
 
-    fn b<B: Buffer<u8>>(_: B) -> io::Result<()> {
-        Ok(())
+    fn b<B: Buffer<u8>>(b: B) -> io::Result<B::Output> {
+        unsafe { Ok(b.assume_init(0)) }
     }
 
     let mut event_buf = [0; 4];
@@ -58,6 +59,33 @@ fn error_retry_closure() {
     retry_on_intr(|| b(&mut *event_buf_slice)).unwrap();
 }
 
+fn error_retry_closure_uninit() {
+    use rustix::buffer::Buffer;
+    use rustix::io;
+    use std::mem::MaybeUninit;
+
+    fn b<B: Buffer<u8>>(b: B) -> io::Result<B::Output> {
+        unsafe { Ok(b.assume_init(0)) }
+    }
+
+    let mut event_buf = [MaybeUninit::<u8>::uninit(); 4];
+
+    // Ideally we'd write this, but it gets:
+    // "captured variable cannot escape `FnMut` closure body".
+    /*
+    rustix::io::retry_on_intr(|| b(&mut event_buf)).unwrap();
+    */
+
+    // The fix: Don't use `retry_on_intr`, unfortunately.
+    loop {
+        match b(&mut event_buf) {
+            Ok((_init, _unini)) => break,
+            Err(io::Errno::INTR) => continue,
+            Err(err) => Err(err).unwrap(),
+        }
+    }
+}
+
 fn error_retry_indirect_closure() {
     use rustix::buffer::Buffer;
     use rustix::io;

src/buffer.rs

@@ -87,6 +87,11 @@ use core::slice;
 /// try replacing `x` with `&mut *x`, or, if that doesn't work, try moving a
 /// `let` into the closure body. See `error_retry_closure` and
 /// `error_retry_indirect_closure` in examples/buffer_errors.rs.
+///
+/// If you see errors like
+/// "captured variable cannot escape `FnMut` closure body",
+/// use an explicit loop instead of `retry_on_intr`, assuming you're using
+/// that. See `error_retry_closure_uninit` in examples.rs.
 pub trait Buffer<T>: private::Sealed<T> {}
 
 // Implement `Buffer` for all the types that implement `Sealed`.