SIBLING_TEMP_FILE Class Reference

A class that owns a sibling temp file, which is created next to the target at construction. More...

Public Member Functions
	SIBLING_TEMP_FILE (const wxString &aTargetPath, const wxChar *aMode)
	SIBLING_TEMP_FILE (const SIBLING_TEMP_FILE &)=delete
	Copy is meaningless: the temp file cannot be shared.
SIBLING_TEMP_FILE &	operator= (const SIBLING_TEMP_FILE &)=delete
	Ditto for assignment: the temp file cannot be shared.
	~SIBLING_TEMP_FILE ()
FILE *	File ()
	The open temp file to write to. Null once Commit() or Abandon() has run.
const wxString &	Path () const
	The temp file's path on disk.
int	Abandon ()
	Abandons the in-progress save: closes the temp file handle without committing, leaving the file on disk for the destructor to discard.
bool	Commit ()
	Flush, close and atomically rename the temp file over the target.

Private Attributes
wxString	m_targetPath
wxString	m_tempPath
FILE *	m_fp = nullptr
bool	m_committed = false

Detailed Description

A class that owns a sibling temp file, which is created next to the target at construction.

The temp file is flushed, closed and renamed over the target on Commit(), the only path that promotes it. Abandon() closes the handle early without committing, and any other uncommitted exit from the object's lifetime (e.g. exception or early return) discards the temp file and leaves the target untouched.

In this way, the target is never truncated or left in a half-written state, and a crash or power loss between construction and Commit() leaves the target untouched.

Definition at line 551 of file richio.cpp.

Constructor & Destructor Documentation

SIBLING_TEMP_FILE() [1/2]

SIBLING_TEMP_FILE::SIBLING_TEMP_FILE ( const wxString & aTargetPath, const wxChar * aMode )

inline

Definition at line 554 of file richio.cpp.

References m_fp, m_targetPath, m_tempPath, KIPLATFORM::IO::OpenUniqueSiblingTempFile(), and THROW_IO_ERROR.

Referenced by operator=(), and SIBLING_TEMP_FILE().

SIBLING_TEMP_FILE() [2/2]

SIBLING_TEMP_FILE::SIBLING_TEMP_FILE ( const SIBLING_TEMP_FILE & )

delete

Copy is meaningless: the temp file cannot be shared.

References SIBLING_TEMP_FILE().

~SIBLING_TEMP_FILE()

SIBLING_TEMP_FILE::~SIBLING_TEMP_FILE ( )

inline

Definition at line 572 of file richio.cpp.

References Abandon(), m_committed, and m_tempPath.

Member Function Documentation

Abandon()

int SIBLING_TEMP_FILE::Abandon ( )

inline

Abandons the in-progress save: closes the temp file handle without committing, leaving the file on disk for the destructor to discard.

Commit() must not be called afterwards: the handle is gone.

Idempotent: calling it again (or after Commit()) is a no-op.

Commit() checks the returned fclose() status because NFS and quota'd volumes can surface write errors at close time, not at write time; an unchecked close could rename a short file into place.

Returns

the fclose() result (0 if the handle was already closed).

Definition at line 606 of file richio.cpp.

References m_fp.

Referenced by Commit(), and ~SIBLING_TEMP_FILE().

Commit()

bool SIBLING_TEMP_FILE::Commit ( )

inline

Flush, close and atomically rename the temp file over the target.

A failure before the rename leaves the target untouched and the destructor discards the temp file. The one exception is a directory-flush failure after the rename has already landed: it throws although the target already holds the new contents, since only their durability is in doubt.

Commit() must be called at most once. Calling it again (whether the first call succeeded or failed) is a programming error, because the temp file is already gone in that case.

Returns

true on a successful commit.

Exceptions

IO_ERROR

if fsync, close, rename, or the directory flush fails.

Definition at line 633 of file richio.cpp.

References _, Abandon(), KIPLATFORM::IO::CommitTempFile(), KIPLATFORM::IO::FlushToDisk(), m_committed, m_fp, m_targetPath, m_tempPath, THROW_IO_ERROR, and THROW_IO_ERRORF.

File()

FILE * SIBLING_TEMP_FILE::File ( )

inline

The open temp file to write to. Null once Commit() or Abandon() has run.

Definition at line 588 of file richio.cpp.

References m_fp.

operator=()

SIBLING_TEMP_FILE & SIBLING_TEMP_FILE::operator= ( const SIBLING_TEMP_FILE & )

delete

Ditto for assignment: the temp file cannot be shared.

References SIBLING_TEMP_FILE().

Path()

const wxString & SIBLING_TEMP_FILE::Path ( ) const

inline

The temp file's path on disk.

Definition at line 591 of file richio.cpp.

References m_tempPath.

Member Data Documentation

m_committed

bool SIBLING_TEMP_FILE::m_committed = false

private

Definition at line 668 of file richio.cpp.

Referenced by Commit(), and ~SIBLING_TEMP_FILE().

m_fp

FILE* SIBLING_TEMP_FILE::m_fp = nullptr

private

Definition at line 667 of file richio.cpp.

Referenced by Abandon(), Commit(), File(), and SIBLING_TEMP_FILE().

m_targetPath

wxString SIBLING_TEMP_FILE::m_targetPath

private

Definition at line 665 of file richio.cpp.

Referenced by Commit(), and SIBLING_TEMP_FILE().

m_tempPath

wxString SIBLING_TEMP_FILE::m_tempPath

private

Definition at line 666 of file richio.cpp.

Referenced by Commit(), Path(), SIBLING_TEMP_FILE(), and ~SIBLING_TEMP_FILE().

---

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

• richio.cpp