Struct git_tempfile::Handle

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

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<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.

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.

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.

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

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 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.