algotradelib::runner::FileJournal Class Reference

The order journal on disk: one JSON object per line, appended and flushed to disk (fsync) before append returns. More...

#include <algotradelib/src/runner/file_journal.hpp>

Public Member Functions
	FileJournal (std::string path, std::string scope)
	Opens a journal file for appending, creating it if absent.
bool	open () const noexcept
	Tests whether the journal opened.
const std::string &	repaired () const noexcept
	Returns what opening had to repair: a torn last line is terminated and a salvaged entry written beside it.
const std::string &	path () const noexcept
	Returns the file's path.
const std::string &	scope () const noexcept
	Returns the journal's broker and account.
const std::string &	rejection () const noexcept
	Returns why the journal refused to open.
bool	append (const JournalEntry &entry)
	Appends one entry and flushes it to disk.
JournalReplay	replay () const
	Reads the whole journal back.

Detailed Description

The order journal on disk: one JSON object per line, appended and flushed to disk (fsync) before append returns.

A write cut short loses only the last line, which shows as missing its newline. Read it with tail. The file starts with a header naming its broker and account; opening a file that belongs to another account is refused.

On POSIX, opening takes an exclusive flock on the file, so a second journal on the same file (in any process) is refused and a program built on it starts nothing. The lock is on the open file, not the path: deleting or renaming the file while it is open lets another journal create and lock a new file at the same path, so do not rotate an active journal. It ends when the process exits, unless a forked child still holds the descriptor (it is closed on exec, not on fork). Keep the journal on a local disk (flock and fsync over NFS are unreliable). Windows takes no lock. A flushed line survives a killed process everywhere; on macOS fsync does not guarantee it survives a power loss. Two journals at different paths for one account are not detected.

Definition at line 1132 of file file_journal.hpp.

Constructor & Destructor Documentation

FileJournal()

algotradelib::runner::FileJournal::FileJournal ( std::string path, std::string scope )

inline

Opens a journal file for appending, creating it if absent.

Never throws for an open failure: check open() and rejection(). A torn last line left by a killed predecessor is repaired first (see repaired()).

Parameters

path	The file.
scope	The broker and account, such as "kis:live:12345678-01"; must not be empty.

Definition at line 1143 of file file_journal.hpp.

Member Function Documentation

append()

bool algotradelib::runner::FileJournal::append ( const JournalEntry & entry )

inline

Appends one entry and flushes it to disk.

The journal's own scope replaces the entry's.

Parameters

entry

The entry.

Returns

true if the line was written whole and flushed.

Definition at line 1244 of file file_journal.hpp.

open()

bool algotradelib::runner::FileJournal::open ( ) const

inlinenoexcept

Tests whether the journal opened.

Returns

true if it is open for appending.

Definition at line 1204 of file file_journal.hpp.

Referenced by append(), and FileJournal().

path()

const std::string & algotradelib::runner::FileJournal::path ( ) const

inlinenoexcept

Returns the file's path.

Returns

The path.

Definition at line 1217 of file file_journal.hpp.

Referenced by FileJournal().

rejection()

const std::string & algotradelib::runner::FileJournal::rejection ( ) const

inlinenoexcept

Returns why the journal refused to open.

The file holds another account's records, has no header, or cannot be read; another writer holds its lock (POSIX); the lock could not be taken; the file could not be opened; a torn last line could not be repaired; or the scope is empty.

Returns

The reason, or empty if it opened.

Definition at line 1234 of file file_journal.hpp.

repaired()

const std::string & algotradelib::runner::FileJournal::repaired ( ) const

inlinenoexcept

Returns what opening had to repair: a torn last line is terminated and a salvaged entry written beside it.

Returns

The description, or empty if nothing was wrong.

Definition at line 1211 of file file_journal.hpp.

replay()

JournalReplay algotradelib::runner::FileJournal::replay ( ) const

inline

Reads the whole journal back.

Returns

The replay, reporting anything that could not be read.

Definition at line 1264 of file file_journal.hpp.

scope()

const std::string & algotradelib::runner::FileJournal::scope ( ) const

inlinenoexcept

Returns the journal's broker and account.

Returns

The scope.

Definition at line 1223 of file file_journal.hpp.

Referenced by FileJournal().

---

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

• algotradelib/src/runner/file_journal.hpp