From 47d103e8a11d11fb5970838502f6a8afde3d0aae Mon Sep 17 00:00:00 2001 From: Max Kellermann Date: Thu, 12 May 2022 16:47:43 +0200 Subject: [PATCH] io/FileOutputStream: add API documentation --- src/io/FileOutputStream.hxx | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/src/io/FileOutputStream.hxx b/src/io/FileOutputStream.hxx index 04d8837de..78fcefc06 100644 --- a/src/io/FileOutputStream.hxx +++ b/src/io/FileOutputStream.hxx @@ -58,6 +58,13 @@ class Path; +/** + * An #OutputStream implementation which writes to a file. + * + * The destructor will attempt to roll back the changes by calling + * Cancel(). To confirm that data shall be written and the existing + * file shall be replaced, call Commit(). + */ class FileOutputStream final : public OutputStream { const AllocatedPath path; @@ -132,13 +139,30 @@ public: return path; } + /** + * Returns the current offset. + */ [[gnu::pure]] uint64_t Tell() const noexcept; /* virtual methods from class OutputStream */ void Write(const void *data, size_t size) override; + /** + * Commit all data written to the file and make the file + * visible on the specified path. + * + * After returning, this object must not be used again. + * + * Throws on error. + */ void Commit(); + + /** + * Attempt to roll back all changes. + * + * After returning, this object must not be used again. + */ void Cancel() noexcept; private: