Expose a File.flush() method to scripting

[Calinou]

Follow-up to #44393.

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).

Note: I couldn't test this as I get "File must be opened before use." when trying to create a new file following the File code sample in the class reference, even with a vanilla master build.

Edit: Using File.WRITE instead of File.READ_WRITE works for testing.

See discussion in #29075.

[Xrayez]

I think this is certainly useful for things like storing game replays where you can continuously write to disk (at some fixed steps via chunks of data, of course), or saving procedurally generated world.

[andy-noisyduck]

Calling flush() on a file that doesn't support flushing (i.e. a file opened with open_compressed, or open_encrypted) will be silently ignored. Is this the desired behaviour?

Edit: It seems the behaviour isn't consistent between the types. A packed file (PackedData) will error if flush is called. Calling flush on a compressed will error if it was opened as a zip, but fail silently if another compression scheme is used.

These problems are existing and not caused by this PR - though previously you couldn't trigger them in scripts due to the lack of the bind. Perhaps this is fine (it's certainly better than it was), and we should just open another ticket for the correction.

[Xrayez]

Those problems should be treated on the same level, regardless of whether the functionality is exposed (because it's possible to do the same thing via C++ modules currently), so I'm for consistency in this case (and yes, if that's the case, people will report more issues with this, but I don't see nothing wrong with that).

Calling flush() on a file that doesn't support flushing (i.e. a file opened with open_compressed, or open_encrypted) will be silently ignored. Is this the desired behaviour?

I wonder what would be the alternative way to write compressed data? Perhaps the partial data/buffer should be manually compressed before write in this case (via PackedByteArray.compress())?

[akien-mga]

Note: I couldn't test this as I get "File must be opened before use." when trying to create a new file following the File code sample in the class reference, even with a vanilla master build.

Does it work in 3.2?

[akien-mga]

Note: I couldn't test this as I get "File must be opened before use." when trying to create a new file following the File code sample in the class reference, even with a vanilla master build.

Does it work in 3.2?

Bump. Could also use a rebase to make sure it builds fine after various refactorings.

[Calinou]

Rebased and tested on master and 3.2, it works successfully. I've also added more documentation about flushing and closing files.

[akien-mga]

Thanks!

[akien-mga]

Cherry-picked for 3.2.4.