Struct Handle

pub struct Handle<Marker: Debug> { /* private fields */ }

A registered temporary file which will delete itself on drop or if the program is receiving signals that should cause it to terminate.

Note

Signals interrupting the calling thread right after taking ownership of the registered tempfile will cause all but this tempfile to be removed automatically. In the common case it will persist on disk as destructors were not called or didn’t get to remove the file.

In the best case the file is a true temporary with a non-clashing name that ‘only’ fills up the disk, in the worst case the temporary file is used as a lock file which may leave the repository in a locked state forever.

This kind of raciness exists whenever take() is used and can’t be circumvented.

Implementations

impl Handle<Writable>

pub fn persist( self, path: impl AsRef<Path>, ) -> Result<Option<File>, Error<Writable>>

Persist this tempfile to replace the file at the given path if necessary, in a way that recovers the original instance on error or returns the open now persisted former tempfile. Note that it might not exist anymore if an interrupt handler managed to steal it and allowed the program to return to its normal flow.

impl Handle<Closed>

pub fn persist(self, path: impl AsRef<Path>) -> Result<(), Error<Closed>>

Persist this tempfile to replace the file at the given path if necessary, in a way that recovers the original instance on error.

impl Handle<Closed>

Creation and ownership transfer

pub fn at( path: impl AsRef<Path>, directory: ContainingDirectory, cleanup: AutoRemove, ) -> Result<Self>

Create a registered tempfile at the given path, where path includes the desired filename and close it immediately.

Depending on the directory configuration, intermediate directories will be created, and depending on cleanup empty intermediate directories will be removed.

Warning of potential leaks

Without signal handlers installed, tempfiles will remain once a termination signal is encountered as destructors won’t run. See the top-level documentation for more.

pub fn at_with_permissions( path: impl AsRef<Path>, directory: ContainingDirectory, cleanup: AutoRemove, permissions: Permissions, ) -> Result<Self>

Like at, but with support for filesystem permissions.

pub fn take(self) -> Option<TempPath>

Take ownership of the temporary file path, which deletes it when dropped without persisting it beforehand.

It’s a theoretical possibility that the file isn’t present anymore if signals interfere, hence the Option

impl Handle<Writable>

Creation and ownership transfer

pub fn at( path: impl AsRef<Path>, directory: ContainingDirectory, cleanup: AutoRemove, ) -> Result<Self>

Create a registered tempfile at the given path, where path includes the desired filename.

Depending on the directory configuration, intermediate directories will be created, and depending on cleanup empty intermediate directories will be removed.

Warning of potential leaks

Without signal handlers installed, tempfiles will remain once a termination signal is encountered as destructors won’t run. See the top-level documentation for more.

pub fn at_with_permissions( path: impl AsRef<Path>, directory: ContainingDirectory, cleanup: AutoRemove, permissions: Permissions, ) -> Result<Self>

Like at, but with support for filesystem permissions.

pub fn new( containing_directory: impl AsRef<Path>, directory: ContainingDirectory, cleanup: AutoRemove, ) -> Result<Self>

Create a registered tempfile within containing_directory with a name that won’t clash, and clean it up as specified with cleanup. Control how to deal with intermediate directories with directory. The temporary file is opened and can be written to using the with_mut() method.

Warning of potential leaks

Without signal handlers installed, tempfiles will remain once a termination signal is encountered as destructors won’t run. See the top-level documentation for more.

pub fn take(self) -> Option<NamedTempFile>

Take ownership of the temporary file.

It’s a theoretical possibility that the file isn’t present anymore if signals interfere, hence the Option

pub fn close(self) -> Result<Handle<Closed>>

Close the underlying file handle but keep track of the temporary file as before for automatic cleanup.

This saves system resources in situations where one opens a tempfile file at a time, writes a new value, and closes it right after to perform more updates of this kind in other tempfiles. When all succeed, they can be renamed one after another.

impl Handle<Writable>

Mutation

pub fn with_mut<T>( &mut self, once: impl FnOnce(&mut NamedTempFile) -> T, ) -> Result<T>

Obtain a mutable handler to the underlying named tempfile and call f(&mut named_tempfile) on it.

Note that for the duration of the call, a signal interrupting the operation will cause the tempfile not to be cleaned up as it is not visible anymore to the signal handler.

Assumptions

The caller must assure that the signal handler for cleanup will be followed by an abort call so that this code won’t run again on a removed instance. An error will occur otherwise.

Trait Implementations

impl<Marker: Debug + Debug> Debug for Handle<Marker>

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

Formats the value using the given formatter.

impl<T: Debug> Drop for Handle<T>

fn drop(&mut self)

Executes the destructor for this type.

impl Read for Handle<Writable>

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

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

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

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

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.

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

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

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

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

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

Reads the exact number of bytes required to fill buf.

fn read_buf(&mut self, buf: BorrowedCursor<'_>) -> Result<(), Error>

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

Pull some bytes from this source into the specified buffer.

fn read_buf_exact(&mut self, cursor: BorrowedCursor<'_>) -> Result<(), Error>

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

Reads the exact number of bytes required to fill cursor.

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

where Self: Sized,

Creates a “by reference” adaptor for this instance of Read.

fn bytes(self) -> Bytes<Self>

where Self: Sized,

Transforms this Read instance to an Iterator over its bytes.

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

where R: Read, Self: Sized,

Creates an adapter which will chain this stream with another.

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

where Self: Sized,

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

impl Seek for Handle<Writable>

fn seek(&mut self, pos: SeekFrom) -> Result<u64>

Seek to an offset, in bytes, in a stream.

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

Rewind to the beginning of a stream.

fn stream_len(&mut self) -> Result<u64, Error>

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

Returns the length of this stream (in bytes).

fn stream_position(&mut self) -> Result<u64, Error>

Returns the current seek position from the start of the stream.

fn seek_relative(&mut self, offset: i64) -> Result<(), Error>

Seeks relative to the current position.

impl Write for Handle<Writable>

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

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

fn flush(&mut self) -> Result<()>

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

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

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

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.

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

Attempts to write an entire buffer into this writer.

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.

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

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

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

where Self: Sized,

Creates a “by reference” adapter for this instance of Write.