Expand FileStreamOptions.PreallocationSize description #7289

carlossanlop · 2021-10-13T16:21:12Z

As discussed in dotnet/runtime#59705 , we want to make sure the documentation is clear and detailed on how to use System.IO.FileStreamOptions.PreallocationSize.

ghost · 2021-10-13T16:21:14Z

Tagging subscribers to this area: @carlossanlop
See info in area-owners.md if you want to be subscribed.

Issue Details

null

Author:	carlossanlop
Assignees:	carlossanlop
Labels:	`area-System.IO`
Milestone:	-

xml/System.IO/FileStreamOptions.xml

Co-authored-by: Adam Sitnik <adam.sitnik@gmail.com>

…otnet-api-docs into PreallocationSize

xml/System.IO/FileStream.xml

xml/System.IO/FileStreamOptions.xml

Co-authored-by: Genevieve Warren <24882762+gewarren@users.noreply.github.com>

xml/System.IO/FileStreamOptions.xml

tmds · 2021-10-14T07:03:06Z

samples/snippets/csharp/System.IO/FileStreamOptions/PreallocationSizeExample.cs

+        };
+        using var destination = new FileStream(DestinationPath, createForWriting);
+
+        source.CopyTo(destination);


This is good for showing PreallocationSize usage, but there are better ways to copy a file.

If you'd want to use a more 'realistic' use-case, you could consider something like:

write a large file with random data.

download a large file using HttpClient.

I'd like to keep the main code example as simple as possible. Mixing HttpClient here would be distracting.

I'm not opposed to adding a separate code example showing what you described though. We can add as many code examples as we want. But the main one should be simple.

xml/System.IO/FileStreamOptions.xml

Co-authored-by: Günther Foidl <gue@korporal.at>

xml/System.IO/FileStreamOptions.xml

carlossanlop · 2021-10-14T16:06:22Z

xml/System.IO/FileStreamOptions.xml

+
+The file length is dependent on how many bytes were actually written to the file, not on how many were requested to be preallocated.
+
+For example: if the user preallocates a 2 GB file, but writes only 1 GB to it, the final file length will be 1 GB.


@adamsitnik here's your suggestion, but changed size for length:

Suggested change

For example: if the user preallocates a 2 GB file, but writes only 1 GB to it, the final file length will be 1 GB.

For example, if the user preallocates a 2 GB file, but writes only 1 GB to it, the allocated size will be 2 GB until the file gets closed, and after that, the length will be reported as 1 GB.

but changed size for length

I think that this is wrong. The size will be reported as 2 GB until the fd is closed.

I am not 100% sure so most probably you should write some small console app and verify it.

Do you mean changing size to length is incorrect?

- The length will be 2 GB until the file gets closed, and after that, the length will be reported as 1 GB. + The size will be 2 GB until the file gets closed, and after that, the size will be reported as 1 GB.

I prefer the word length as it describes the position of the EOF.
size is more ambiguous, it can either be length, or the amount of space allocated (cfr preallocationSize).

When you close the file on Linux, the length will be 1 GB, and the allocated size for it will still be 2 GB.

Ok, so I think my suggestion above is the correct one. LTM if you feel like I should change it.

When you close the file on Linux, the length will be 1 GB, and the allocated size for it will still be 2 GB.

Isn't that a bug? Also, is there a way to revert the size to match the length? I wonder if using preallocation size you may end up with a full disk sooner than not using it.

Also, is there a way to revert the size to match the length?

Not using available .NET APIs.

I wonder if using preallocation size you may end up with a full disk sooner than not using it.

If you use this to specify the length of the file you're about to write, the difference should not be an issue.
If you specify a large value and only write a small file, you'll be wasting disk space if you don't intent to write to it further.

Not using available .NET APIs.

What about with unix syscalls? Furthermore, I wonder if it may be a good idea to free the unused blocks when the FileStream gets Dispose'd.

On Linux, fallocate can also be used to deallocate.

xml/System.IO/FileStreamOptions.xml

xml/System.IO/FileStream.xml

carlossanlop · 2021-10-15T14:23:52Z

@gewarren would you mind taking a look once again? I made several modifications after your sign-off.

gewarren · 2021-10-15T16:08:38Z

xml/System.IO/FileStreamOptions.xml

-        <summary>The initial allocation size in bytes for the file. A positive value is effective only when a regular file is being created, overwritten, or replaced.
-            Negative values are not allowed.
-            In other cases (including the default 0 value), it's ignored.</summary>
+        <summary>The initial allocation size in bytes for the file. A positive value is effective only when a regular file is being created or overwritten (<see cref="F:System.IO.FileMode.Create"/> or <see cref="F:System.IO.FileMode.CreateNew"/>). Negative values are not allowed. In other cases (including the default 0 value), it's ignored. This value is a hint and is not a strong guarantee. It is not supported on Web Assembly (WASM) and FreeBSD (the value is ignored). For Windows, Linux and macOS we will try to preallocate the disk space to fill the requested allocation size. If that turns out to be impossible, the operation is going to throw an exception. The final file length (EOF) will be determined by the number of bytes written to the file.</summary>


This seems too long for a summary, and some of it is repeated in the remarks. I'd suggest something like:

Suggested change

<summary>The initial allocation size in bytes for the file. A positive value is effective only when a regular file is being created or overwritten (<see cref="F:System.IO.FileMode.Create"/> or <see cref="F:System.IO.FileMode.CreateNew"/>). Negative values are not allowed. In other cases (including the default 0 value), it's ignored. This value is a hint and is not a strong guarantee. It is not supported on Web Assembly (WASM) and FreeBSD (the value is ignored). For Windows, Linux and macOS we will try to preallocate the disk space to fill the requested allocation size. If that turns out to be impossible, the operation is going to throw an exception. The final file length (EOF) will be determined by the number of bytes written to the file.</summary>

<summary>The initial allocation size in bytes for the file. For important details, see the Remarks section of the docs.</summary>

@gewarren It was done on purpose. We want the PreallocationSize summary to contain all the info in IntelliSense.

Suggested change

<summary>The initial allocation size in bytes for the file. A positive value is effective only when a regular file is being created or overwritten (<see cref="F:System.IO.FileMode.Create"/> or <see cref="F:System.IO.FileMode.CreateNew"/>). Negative values are not allowed. In other cases (including the default 0 value), it's ignored. This value is a hint and is not a strong guarantee. It is not supported on Web Assembly (WASM) and FreeBSD (the value is ignored). For Windows, Linux and macOS we will try to preallocate the disk space to fill the requested allocation size. If that turns out to be impossible, the operation is going to throw an exception. The final file length (EOF) will be determined by the number of bytes written to the file.</summary>

<summary>The initial allocation size in bytes for the file. A positive value is effective only when a regular file is being created or overwritten (<see cref="F:System.IO.FileMode.Create"/> or <see cref="F:System.IO.FileMode.CreateNew"/>). Negative values are not allowed. In other cases (including the default 0 value), it's ignored. This value is a hint and is not a strong guarantee. It is not supported on Web Assembly (WASM) and FreeBSD (the value is ignored). For Windows, Linux, and macOS, .NET attempts to preallocate the disk space to fill the requested allocation size. If that is unsuccessful, the operation throws an exception. The final file length (EOF) is determined by the number of bytes written to the file.</summary>

xml/System.IO/FileStreamOptions.xml

adamsitnik

LGTM, big thanks for writing it down @carlossanlop !

BTW I love all these OS differences. They make our job so easy...

samples/snippets/csharp/System.IO/FileStreamOptions/PreallocationSizeExample.cs

xml/System.IO/FileStreamOptions.xml

Co-authored-by: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Co-authored-by: Adam Sitnik <adam.sitnik@gmail.com>

opbld33 · 2021-10-15T18:10:52Z

Docs Build status updates of commit 0154397:

✅ Validation status: passed

File	Status	Preview URL
samples/snippets/csharp/System.IO/FileStreamOptions/FileStreamOptionsExamples.csproj	✅Succeeded
samples/snippets/csharp/System.IO/FileStreamOptions/PreallocationSizeExample.cs	✅Succeeded	View
samples/snippets/visualbasic/System.IO/FileStreamOptions/FileStreamOptionsExamples.vbproj	✅Succeeded
samples/snippets/visualbasic/System.IO/FileStreamOptions/PreallocationSizeExample.vb	✅Succeeded	View
xml/System.IO/FileStream.xml	✅Succeeded	View
xml/System.IO/FileStreamOptions.xml	✅Succeeded	View

For more details, please refer to the build report.

Note: Broken links written as relative paths are included in the above build report. For broken links written as absolute paths or external URLs, see the broken link report.

For any questions, please:

Try searching the docs.microsoft.com contributor guides
Post your question in the Docs support channel

Expand FileStreamOptions.PreallocationSize description.

e4beb24

carlossanlop added the area-System.IO label Oct 13, 2021

carlossanlop self-assigned this Oct 13, 2021

carlossanlop commented Oct 13, 2021

View reviewed changes

xml/System.IO/FileStreamOptions.xml Show resolved Hide resolved

adamsitnik reviewed Oct 13, 2021

View reviewed changes

xml/System.IO/FileStreamOptions.xml Outdated Show resolved Hide resolved

xml/System.IO/FileStreamOptions.xml Outdated Show resolved Hide resolved

xml/System.IO/FileStreamOptions.xml Outdated Show resolved Hide resolved

This comment has been minimized.

Sign in to view

Apply suggestions from code review

e59c998

Co-authored-by: Adam Sitnik <adam.sitnik@gmail.com>

This comment has been minimized.

Sign in to view

carlossanlop added 5 commits October 13, 2021 13:19

Source code samples and projects.

1f325d5

Bold undefined.

fa5a81e

Merge branch 'PreallocationSize' of https://github.com/carlossanlop/d…

ecf9578

…otnet-api-docs into PreallocationSize

FileStreamOptions code examples in remarks

b0bf64d

Fix build failure xrefs to see crefs

82ea08b

This comment has been minimized.

Sign in to view

FileStream constructor remark

949b21a

carlossanlop requested a review from jozkee October 13, 2021 18:34

carlossanlop marked this pull request as ready for review October 13, 2021 18:38

carlossanlop requested review from a team as code owners October 13, 2021 18:38

carlossanlop requested review from stephentoub and tmds October 13, 2021 18:38

gewarren approved these changes Oct 13, 2021

View reviewed changes

xml/System.IO/FileStream.xml Outdated Show resolved Hide resolved

xml/System.IO/FileStream.xml Outdated Show resolved Hide resolved

xml/System.IO/FileStream.xml Outdated Show resolved Hide resolved

This comment has been minimized.

Sign in to view

carlossanlop commented Oct 13, 2021

View reviewed changes

xml/System.IO/FileStreamOptions.xml Outdated Show resolved Hide resolved

xml/System.IO/FileStreamOptions.xml Outdated Show resolved Hide resolved

Apply suggestions from code review

c00ed15

Co-authored-by: Genevieve Warren <24882762+gewarren@users.noreply.github.com>

This comment has been minimized.

Sign in to view

carlossanlop mentioned this pull request Oct 13, 2021

Add csproj file for String C# code samples #7288

Closed

tmds reviewed Oct 14, 2021

View reviewed changes

xml/System.IO/FileStreamOptions.xml Outdated Show resolved Hide resolved

tmds reviewed Oct 14, 2021

View reviewed changes

gfoidl reviewed Oct 14, 2021

View reviewed changes

xml/System.IO/FileStreamOptions.xml Outdated Show resolved Hide resolved

xml/System.IO/FileStreamOptions.xml Outdated Show resolved Hide resolved

Update xml/System.IO/FileStreamOptions.xml

c08e4ef

Co-authored-by: Günther Foidl <gue@korporal.at>

This comment has been minimized.

Sign in to view

carlossanlop commented Oct 14, 2021

View reviewed changes

xml/System.IO/FileStreamOptions.xml Outdated Show resolved Hide resolved

Apply suggestions from code review

4a0e785

carlossanlop commented Oct 14, 2021

View reviewed changes

xml/System.IO/FileStreamOptions.xml Outdated Show resolved Hide resolved

carlossanlop commented Oct 14, 2021

View reviewed changes

xml/System.IO/FileStreamOptions.xml Outdated Show resolved Hide resolved

carlossanlop commented Oct 14, 2021

View reviewed changes

Apply suggestions from code review

19ff8aa

This comment has been minimized.

Sign in to view

Update xml/System.IO/FileStreamOptions.xml

4b1bdde

carlossanlop commented Oct 14, 2021

View reviewed changes

xml/System.IO/FileStreamOptions.xml Outdated Show resolved Hide resolved

This comment has been minimized.

Sign in to view

tmds reviewed Oct 15, 2021

View reviewed changes

xml/System.IO/FileStream.xml Outdated Show resolved Hide resolved

Apply suggestions from code review

ed4cbe4

This comment has been minimized.

Sign in to view

Typo in FileStreamOptions summary

d04d79b

This comment has been minimized.

Sign in to view

gewarren reviewed Oct 15, 2021

View reviewed changes

adamsitnik approved these changes Oct 15, 2021

View reviewed changes

carlossanlop and others added 2 commits October 15, 2021 11:51

Apply suggestions from code review

aea8701

Co-authored-by: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Co-authored-by: Adam Sitnik <adam.sitnik@gmail.com>

Simplify code samples

0154397

This comment has been minimized.

Sign in to view

carlossanlop merged commit 8dc75ac into dotnet:main Oct 15, 2021

carlossanlop deleted the PreallocationSize branch October 15, 2021 18:45


		The file length is dependent on how many bytes were actually written to the file, not on how many were requested to be preallocated.

		For example: if the user preallocates a 2 GB file, but writes only 1 GB to it, the final file length will be 1 GB.

	For example: if the user preallocates a 2 GB file, but writes only 1 GB to it, the final file length will be 1 GB.
	For example, if the user preallocates a 2 GB file, but writes only 1 GB to it, the allocated size will be 2 GB until the file gets closed, and after that, the length will be reported as 1 GB.

Expand FileStreamOptions.PreallocationSize description #7289

Expand FileStreamOptions.PreallocationSize description #7289

Uh oh!

Conversation

carlossanlop commented Oct 13, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ghost commented Oct 13, 2021

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

Uh oh!

Uh oh!

Uh oh!

This comment has been minimized.

Uh oh!

Uh oh!

This comment has been minimized.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

This comment has been minimized.

Uh oh!

Uh oh!

Uh oh!

carlossanlop Oct 14, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jozkee Oct 15, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

This comment has been minimized.

This comment has been minimized.

Uh oh!

This comment has been minimized.

Uh oh!

carlossanlop commented Oct 15, 2021

Uh oh!

This comment has been minimized.

This comment has been minimized.

Choose a reason for hiding this comment

Uh oh!

carlossanlop Oct 15, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gewarren Oct 15, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

carlossanlop commented Oct 13, 2021 •

edited

Loading

carlossanlop Oct 14, 2021 •

edited

Loading

jozkee Oct 15, 2021 •

edited

Loading

carlossanlop Oct 15, 2021 •

edited

Loading

gewarren Oct 15, 2021 •

edited

Loading