tmpfile

TmpFile is an object representing a temporary file that can optionally be persisted.

lib.rs:

Temporary file object that can be persisted.

Usage overview

The main type of this crate is TmpFile, which represents a (temporary) file being written to, that may optionally be persisted (or it will be removed).

To use TmpFile an application must first implement the TmpProc trait on a type. [TmpProc::update()] will be called each time a block of data is written to the TmpFile. [TmpProc::finalize()] will be called if the application chooses to persist the TmpFile.

When a TmpFile is created, the application must pass along the file's temporary location and an object whose type implements TmpProc. The instantiated TmpFile object implements std::io::Write, which is used to write data to it.

If the entire file can not be completed, the TmpFile object is dropped, which will automatically remove the temporary file.

If the entire file has been written, and the application wants to persist it, it calls [TmpFile::persist()]. This will call the TmpProc::finalize() trait method, whose responsibility it is to return the file's persistent location (and application-defined data). Information about the persisted file is finally returned to the application via an instantion of Persisted.

"Small file" special case

An application may not want to store small files in its filesystem. For this purpose, the TmpFile can be set up to have a minimum file size. If a TmpFile does not reach this size before being persisted, a memory buffer of the file's contents will be returned instead of a file name of the persisted file.

The [TmpFile::with_minsize()] factory method can be used to use this feature.

Deferred persist

There may be cases where it's impractical to call [TmpFile::persist()] on a TmpFile, but where the originator of the TmpFile wants to manage the results from the TmpFile when it is pesisted. This crate has means to handle such situations, but it drastically changes the semantics of TmpFile: The defer_persist() method returns a wait context that can be used to wait for the TmpFile to finalize and send its results. In this scenario, the finalization occurrs implicitly when the TmpFile is dropped.

This means that deferred persist shifts the default assumption of "drop-before-persist implies failure" to "drop means persist", with no means to trigger "abort without finalization" (unless the TmpProc's finalization is able to determine that the file is incomplete).

Features