From 6c6f4e9895a88595be38977ac0134cf045d9a20e Mon Sep 17 00:00:00 2001 From: Hugo Locurcio Date: Tue, 15 Dec 2020 15:31:04 +0100 Subject: [PATCH] Expose a `File.flush()` method to scripting This can be used to ensure a file has its contents saved even if the project crashes or is killed by the user (among other use cases). See discussion in #29075. (cherry picked from commit ab397460e9f8ea36414eb1b11d76c3e223decdcc) --- core/bind/core_bind.cpp | 6 ++++++ core/bind/core_bind.h | 1 + doc/classes/File.xml | 11 ++++++++++- 3 files changed, 17 insertions(+), 1 deletion(-) diff --git a/core/bind/core_bind.cpp b/core/bind/core_bind.cpp index c0387ec59f5..5750a6ef13f 100644 --- a/core/bind/core_bind.cpp +++ b/core/bind/core_bind.cpp @@ -1992,6 +1992,11 @@ Error _File::open(const String &p_path, ModeFlags p_mode_flags) { return err; } +void _File::flush() { + ERR_FAIL_COND_MSG(!f, "File must be opened before flushing."); + f->flush(); +} + void _File::close() { if (f) @@ -2308,6 +2313,7 @@ void _File::_bind_methods() { ClassDB::bind_method(D_METHOD("open_compressed", "path", "mode_flags", "compression_mode"), &_File::open_compressed, DEFVAL(0)); ClassDB::bind_method(D_METHOD("open", "path", "flags"), &_File::open); + ClassDB::bind_method(D_METHOD("flush"), &_File::flush); ClassDB::bind_method(D_METHOD("close"), &_File::close); ClassDB::bind_method(D_METHOD("get_path"), &_File::get_path); ClassDB::bind_method(D_METHOD("get_path_absolute"), &_File::get_path_absolute); diff --git a/core/bind/core_bind.h b/core/bind/core_bind.h index 6f1bae02d57..db0a9798d0c 100644 --- a/core/bind/core_bind.h +++ b/core/bind/core_bind.h @@ -507,6 +507,7 @@ public: Error open_compressed(const String &p_path, ModeFlags p_mode_flags, CompressionMode p_compress_mode = COMPRESSION_FASTLZ); Error open(const String &p_path, ModeFlags p_mode_flags); // open a file. + void flush(); // Flush a file (write its buffer to disk). void close(); // Close a file. bool is_open() const; // True when file is open. diff --git a/doc/classes/File.xml b/doc/classes/File.xml index edcda1ae787..cfa9528aa7a 100644 --- a/doc/classes/File.xml +++ b/doc/classes/File.xml @@ -22,6 +22,7 @@ [/codeblock] In the example above, the file will be saved in the user data folder as specified in the [url=https://docs.godotengine.org/en/3.2/tutorials/io/data_paths.html]Data paths[/url] documentation. [b]Note:[/b] To access project resources once exported, it is recommended to use [ResourceLoader] instead of the [File] API, as some files are converted to engine-specific formats and their original source files might not be present in the exported PCK package. + [b]Note:[/b] Files are automatically closed only if the process exits "normally" (such as by clicking the window manager's close button or pressing [b]Alt + F4[/b]). If you stop the project execution by pressing [b]F8[/b] while the project is running, the file won't be closed as the game process will be killed. You can work around this by calling [method flush] at regular intervals. https://docs.godotengine.org/en/3.2/getting_started/step_by_step/filesystem.html @@ -32,7 +33,7 @@ - Closes the currently opened file. + Closes the currently opened file and prevents subsequent read/write operations. Use [method flush] to persist the data to disk without closing the file. @@ -53,6 +54,14 @@ [b]Note:[/b] Many resources types are imported (e.g. textures or sound files), and their source asset will not be included in the exported game, as only the imported version is used. See [method ResourceLoader.exists] for an alternative approach that takes resource remapping into account. + + + + + Writes the file's buffer to disk. Flushing is automatically performed when the file is closed. This means you don't need to call [method flush] manually before closing a file using [method close]. Still, calling [method flush] can be used to ensure the data is safe even if the project crashes instead of being closed gracefully. + [b]Note:[/b] Only call [method flush] when you actually need it. Otherwise, it will decrease performance due to constant disk writes. + +