TfAtomicOfstreamWrapper Class Reference

#include <atomicOfstreamWrapper.h>

Public Member Functions
TF_API	TfAtomicOfstreamWrapper (const std::string &filePath)
	Constructor. More...
TF_API	~TfAtomicOfstreamWrapper ()
	Destructor. Calls Cancel(). More...
TF_API bool	Open (std::string *reason=0)
TF_API bool	Commit (std::string *reason=0)
TF_API bool	Cancel (std::string *reason=0)
	Closes the temporary file and removes it from disk, if it exists. More...
std::ofstream &	GetStream ()

Detailed Description

A class that wraps a file output stream, providing improved tolerance for write failures. The wrapper opens an output file stream to a temporary file on the same file system as the desired destination file, and if no errors occur while writing the temporary file, it can be renamed atomically to the destination file name. In this way, write failures are encountered while writing the temporary file content, rather than while writing the destination file. This ensures that, if the destination existed prior to writing, it is left untouched in the event of a write failure, and if the destination did not exist, a partial file is not written.

Example

// Create a new wrapper with the destination file path.
TfAtomicOfstreamWrapper wrapper("/home/user/realFile.txt");

// Open the wrapped stream.
string reason;
if (not wrapper.Open(&reason)) {
    TF_RUNTIME_ERROR(reason);
}

// Write content to the wrapped stream.
bool ok = WriteContentToStream(wrapper.GetStream());

if (ok) {
    // No errors encountered, rename the temporary file to the real name.
    string reason;
    if (not wrapper.Commit(&reason)) {
        TF_RUNTIME_ERROR(reason);
    }
}

// If wrapper goes out of scope without being Commit()ed, Cancel() is
// called, and the temporary file is removed.

Definition at line 77 of file atomicOfstreamWrapper.h.

Constructor & Destructor Documentation

TF_API TfAtomicOfstreamWrapper::TfAtomicOfstreamWrapper ( const std::string &  filePath )

explicit

Constructor.

TF_API TfAtomicOfstreamWrapper::~TfAtomicOfstreamWrapper

(

)

Destructor. Calls Cancel().

Member Function Documentation

TF_API bool TfAtomicOfstreamWrapper::Cancel

(

std::string *

reason = 0

)

Closes the temporary file and removes it from disk, if it exists.

TF_API bool TfAtomicOfstreamWrapper::Commit

(

std::string *

reason = 0

)

Synchronizes the temporary file contents to disk, and renames the temporary file into the file path passed to Open. If the file path passed to the constructor names an existing file, the file, the file is atomically replaced with the temporary file. If the rename fails, false is returned and reason is set to the reason for failure.

std::ofstream& TfAtomicOfstreamWrapper::GetStream ( )

inline

Returns the stream. If this is called before a call to Open, the returned file stream is not yet initialized. If called after Commit or Cancel, the returned file stream is closed.

Definition at line 110 of file atomicOfstreamWrapper.h.

TF_API bool TfAtomicOfstreamWrapper::Open

(

std::string *

reason = 0

)

Opens the temporary file for writing. If the destination directory does not exist, it is created. If the destination directory exists but is unwritable, the destination directory cannot be created, or the temporary file cannot be opened for writing in the destination directory, this method returns false and reason is set to the reason for failure.

---

The documentation for this class was generated from the following file:

• pxr/base/tf/atomicOfstreamWrapper.h