go/doc/next/6-stdlib/99-minor/os/15388.md

On Windows, [NewFile] now supports handles opened for asynchronous I/O (that is,
[syscall.FILE_FLAG_OVERLAPPED] is specified in the [syscall.CreateFile] call).
These handles are associated with the Go runtime's I/O completion port,
which provides the following benefits for the resulting [File]:

- I/O methods ([File.Read], [File.Write], [File.ReadAt], and [File.WriteAt]) do not block an OS thread.
- Deadline methods ([File.SetDeadline], [File.SetReadDeadline], and [File.SetWriteDeadline]) are supported.

This enhancement is especially beneficial for applications that communicate via named pipes on Windows.

Note that a handle can only be associated with one completion port at a time.
If the handle provided to [NewFile] is already associated with a completion port,
the returned [File] is downgraded to synchronous I/O mode.
In this case, I/O methods will block an OS thread, and the deadline methods have no effect.
os: support overlapped IO with NewFile The runtime/poll package has just gained support for overlapped IO, see CL 660595 and CL 661955. The only remaining piece was making it visible to user code via os.NewFile. Some of the poll.FD.Init responsibility has been moved to os.NewFile to avoid unnecessary syscalls for the common case of using os.Open, os.Create, os.OpenFile, and os.Pipe, where we know that the file is not opened for overlapped IO. Some internal/poll tests have been moved to the os package to exercise public APIs rather than internal ones. The os.NewFile function definition has been moved into an OS-agnostic file to avoid having duplicated documentation and ensure that the caller is aware of its behavior across all platforms. Closes #19098. Cq-Include-Trybots: luci.golang.try:gotip-windows-amd64-longtest,gotip-windows-amd64-race,gotip-windows-arm64 Change-Id: If043f8b34d588cd4b481777203107ed92d660fd9 Reviewed-on: https://go-review.googlesource.com/c/go/+/662236 LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com> Reviewed-by: Damien Neil <dneil@google.com> Reviewed-by: Carlos Amedee <carlos@golang.org> Auto-Submit: Damien Neil <dneil@google.com> 2025-04-02 12:47:32 +02:00			`On Windows, [NewFile] now supports handles opened for asynchronous I/O (that is,`
			`[syscall.FILE_FLAG_OVERLAPPED] is specified in the [syscall.CreateFile] call).`
			`These handles are associated with the Go runtime's I/O completion port,`
			`which provides the following benefits for the resulting [File]:`

			`- I/O methods ([File.Read], [File.Write], [File.ReadAt], and [File.WriteAt]) do not block an OS thread.`
			`- Deadline methods ([File.SetDeadline], [File.SetReadDeadline], and [File.SetWriteDeadline]) are supported.`

			`This enhancement is especially beneficial for applications that communicate via named pipes on Windows.`

			`Note that a handle can only be associated with one completion port at a time.`
			`If the handle provided to [NewFile] is already associated with a completion port,`
			`the returned [File] is downgraded to synchronous I/O mode.`
			`In this case, I/O methods will block an OS thread, and the deadline methods have no effect.`