From eb75e8f561bfd3ed4b82c176354213e277a24dcd Mon Sep 17 00:00:00 2001 From: Ashmeen Kaur <57195160+ashmeenkaur@users.noreply.github.com> Date: Mon, 25 Sep 2023 11:18:58 +0530 Subject: [PATCH] update semantics.md for remove 0 byte file changes (#1391) * update semantics.md for remove 0 byte file changes * review comments * review comments * review comments * review comments * review comments * remove todo --- docs/semantics.md | 29 ++++++++++++++++++++++++----- 1 file changed, 24 insertions(+), 5 deletions(-) diff --git a/docs/semantics.md b/docs/semantics.md index 6a47e89f49..6b179b8844 100644 --- a/docs/semantics.md +++ b/docs/semantics.md @@ -8,11 +8,30 @@ Files that have not been modified are read portion by portion on demand. Cloud S **Writes** -For modifications to existing objects, Cloud Storage FUSE downloads the entire backing object's contents from Cloud Storage. The contents are stored in a local temporary file whose location is controlled by the flag ```--temp-dir```. Later, when the file is closed or fsync'd, Cloud Storage FUSE writes the contents of the local file back to Cloud Storage as a new object generation. Modifying even a single bit of an object results in the full re-upload of the object. The exception is if an append is done to the end of a file, where the original file is at least 2MB, then only the appended content is uploaded. - -For new objects, objects are first written to the same temporary directory as mentioned above, and you will notice an empty file is created in the Cloud Storage bucket as a hold. Upon closing or fsyncing the file, the file is then written to your Cloud Storage bucket, with the existing empty file now reflecting the accurate file size and content. - -As new and modified files are fully staged in the local temporary directory until they are written out to Cloud Storage from being closed or fsync'd, you must ensure that there is enough free space available to handle staged content when writing large files. +For modifications to existing objects, Cloud Storage FUSE downloads the entire +backing object's contents from Cloud Storage. The contents are stored in a local +temporary file whose location is controlled by the flag ```--temp-dir```. Later, +when the file is closed or fsync'd, Cloud Storage FUSE writes the contents of +the local file back to Cloud Storage as a new object generation. Modifying even +a single bit of an object results in the full re-upload of the object. The +exception is if an append is done to the end of a file, where the original file +is at least 2MB, then only the appended content is uploaded. + +For new objects, objects are first written to the same temporary directory as +mentioned above. Upon closing or fsyncing the file, the file is then written to +your Cloud Storage bucket. +As new and modified files are fully staged in the local temporary directory +until they are written out to Cloud Storage, you +must ensure that there is enough free space available to handle staged content +when writing large files. + +- **Note:** Prior to version 1.2.0, you will notice that an empty file is + created in the Cloud Storage bucket as a hold. Upon closing or fsyncing the + file, the file is written to your Cloud Storage bucket, with the existing + empty file now reflecting the accurate file size and content. Starting with + version 1.2, the default behavior is to not create this zero-byte file, which + increases write performance. If needed, it can be re-enabled by setting + the `create-empty-file: true` configuration in the config file. **Concurrency**