Struct reopen::Reopen

pub struct Reopen<FD> { /* fields omitted */ }

A Read/Write proxy that can reopen the underlying object.

It is constructed with a function that can open a new instance of the object. If it is signaled to reopen it (though handle), it drops the old instance and uses the function to create a new one at the next IO operation.

Error handling

The reopening is performed lazily, on the first operation done to the object. Opening a new instance can fail with an error. If this happens, the error is returned as part of the operation being performed ‒ therefore, you can get an error like File not found while performing read.

If an error happens, the operation is aborted. Next time an operation is performed, another attempt to open the object is made (which in turn can fail again).

Scheduling of a reopen

The implementation tries to ensure whole operations happen on the same FD. For example, even if multiple read calls need to be performed as part of read_exact, the Reopen will check for reopening flags only once before the whole operation and then will keep the same FD.

If this is not enough, the Reopen can be locked to bundle multiple operations without reopening.

Handling of ends

Certain operations make ordinary file descriptors „finished“ ‒ for example, read_to_end. Usually, further calls to any read operations would produce EOF from then on.

While this reaches the end of the currently opened FD and further read operations would still produce EOF, reopening the FD may lead to it being readable again. Therefore, reaching EOF is not necessarily final for Reopen.

Implementations

impl<FD> Reopen<FD>

pub fn new(
    constructor: Box<dyn Fn() -> Result<FD, Error> + Send>
) -> Result<Self, Error>

Creates a new instance.

pub fn with_handle(
    handle: Handle,
    constructor: Box<dyn Fn() -> Result<FD, Error> + Send>
) -> Result<Self, Error>

Creates a new instance from the given handle.

This might come useful if you want to create the handle beforehand with Handle::stub (eg. in once_cell).

Note that using the same handle for multiple Reopens will not work as expected (the first one to be used resets the signal and the others don't reopen).

Examples

// Something that implements `Write`, for example.
struct Writer;

let handle = Handle::stub();
let reopen = Reopen::with_handle(handle.clone(), Box::new(|| Ok(Writer)));

handle.reopen();

pub fn handle(&self) -> Handle

Returns a handle to signal this Reopen to perform the reopening.

pub fn lock(&mut self) -> Result<&mut FD, Error>

Lock the Reopen against reopening in the middle of operation.

In case of needing to perform multiple operations without reopening in the middle, it can be locked by this method. This provides access to the inner FD.

Errors

This can result in an error in case the FD needs to be reopened (or wasn't opened previously) and the reopening results in an error.

Examples

let mut writer = Reopen::new(Box::new(|| {
    // Vec::<u8> is an in-memory writer
    Ok(Vec::new())
}))?;
let handle = writer.handle();
let mut lock = writer.lock()?;
write!(&mut lock, "Hello ")?;

// Request reopening. But as we locked, it won't happen until we are done with it.
handle.reopen();

write!(&mut lock, "world")?;

// See? Both writes are here now.
assert_eq!(b"Hello world", &lock[..]);

// But when we return to using the writer directly (and drop the lock by that), it gets
// reopened and we get a whole new Vec to play with.
write!(&mut writer, "Another message")?;
assert_eq!(b"Another message", &writer.lock()?[..]);

Trait Implementations

impl<FD: Debug> Debug for Reopen<FD>

pub fn fmt(&self, f: &mut Formatter<'_>) -> FmtResult

Formats the value using the given formatter.

impl<FD: Read> Read for Reopen<FD>

pub fn read(&mut self, buf: &mut [u8]) -> Result<usize, Error>

Pull some bytes from this source into the specified buffer, returning how many bytes were read.

pub fn read_exact(&mut self, buf: &mut [u8]) -> Result<(), Error>

Read the exact number of bytes required to fill buf.

pub fn read_to_end(&mut self, buf: &mut Vec<u8>) -> Result<usize, Error>

Read all bytes until EOF in this source, placing them into buf.

pub fn read_to_string(&mut self, buf: &mut String) -> Result<usize, Error>

Read all bytes until EOF in this source, appending them to buf.

pub fn read_vectored(
    &mut self,
    bufs: &mut [IoSliceMut<'_>]
) -> Result<usize, Error>

Like read, except that it reads into a slice of buffers.

pub fn is_read_vectored(&self) -> bool

🔬 This is a nightly-only experimental API. (can_vector)

Determines if this Reader has an efficient read_vectored implementation.

pub unsafe fn initializer(&self) -> Initializer

🔬 This is a nightly-only experimental API. (read_initializer)

Determines if this Reader can work with buffers of uninitialized memory.

pub fn by_ref(&mut self) -> &mut Self

Creates a "by reference" adaptor for this instance of Read.

pub fn bytes(self) -> Bytes<Self>

Transforms this Read instance to an Iterator over its bytes.

pub fn chain<R>(self, next: R) -> Chain<Self, R> where
    R: Read, 

Creates an adaptor which will chain this stream with another.

pub fn take(self, limit: u64) -> Take<Self>

Creates an adaptor which will read at most limit bytes from it.

impl<FD: Write> Write for Reopen<FD>

pub fn flush(&mut self) -> Result<(), Error>

Flush this output stream, ensuring that all intermediately buffered contents reach their destination.

pub fn write(&mut self, buf: &[u8]) -> Result<usize, Error>

Write a buffer into this writer, returning how many bytes were written.

pub fn write_all(&mut self, buf: &[u8]) -> Result<(), Error>

Attempts to write an entire buffer into this writer.

pub fn write_fmt(&mut self, fmt: Arguments<'_>) -> Result<(), Error>

Writes a formatted string into this writer, returning any error encountered.

pub fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> Result<usize, Error>

Like write, except that it writes from a slice of buffers.

pub fn is_write_vectored(&self) -> bool

🔬 This is a nightly-only experimental API. (can_vector)

Determines if this Writer has an efficient write_vectored implementation.

pub fn write_all_vectored(
    &mut self,
    bufs: &mut [IoSlice<'_>]
) -> Result<(), Error>

🔬 This is a nightly-only experimental API. (write_all_vectored)

Attempts to write multiple buffers into this writer.

pub fn by_ref(&mut self) -> &mut Self

Creates a "by reference" adaptor for this instance of Write.