|RFC-0156: Stream Append Mode|
Add an append mode to streams.
|Date submitted (year-month-day)||2022-04-06|
|Date reviewed (year-month-day)||2022-04-20|
This RFC proposes modifying the stream API by adding an
append mode to streams and removing the append option from
The stream append option,
ZX_STREAM_APPEND, is currently only used in the C++
VFS for implementing
fuchsia.io/File.Write for memfs. All of the memfs streams
live on the server side of the FIDL connection where the append mode of the
connection is known. Accessing the append mode to optionally pass
ZX_STREAM_APPEND to each
zx_stream_writev call works for this specific
With the implementation of writeback for userspace pagers, streams can be sent to the client side of the FIDL connection to significantly increase IO performance. Moving streams to the client side, with the current stream API, will require fdio to keep track of the append mode of the connection.
The goal of this design is to avoid keeping track of the append mode in fdio and bring the stream API more inline with POSIX.
The stream API is very similar to reading, writing, and seeking a file
in POSIX, with the exception of how appends are handled. In POSIX a file can be
opened in append mode by passing
open. All POSIX
to a file in append mode behave similarly to
zx_stream_writev with the
Adding an append mode to streams will avoid fdio storing the append mode and be
more inline with POSIX. With this addition, the
ZX_STREAM_APPEND option for
zx_stream_writev is no longer necessary.
This RFC consists of 3 API changes:
A new option for
ZX_STREAM_MODE_APPEND, will be added. A stream created with
ZX_STREAM_MODE_APPENDwill be placed in append mode. All
zx_stream_writevcalls to a stream in append mode will behave as if
ZX_STREAM_APPENDwas passed to the
A new property named
ZX_PROP_STREAM_MODE_APPENDwill be added. This property is necessary for fdio to implement
ZX_PROP_STREAM_MODE_APPENDwill have a value type of
ZX_PROP_STREAM_MODE_APPENDand a value of
0will take a stream out of append mode.
ZX_PROP_STREAM_MODE_APPENDand any value other than
0will put a stream into append mode.
ZX_PROP_STREAM_MODE_APPENDthe property will have a value of
1if the stream is in append and a value of
0if the stream is not in append mode.
zx_stream_writevwill be removed.
This RFC will be implemented in 3 Gerrit changes:
ZX_PROP_STREAM_MODE_APPENDto the stream API.
Migrate the C++ VFS from
ZX_STREAM_APPENDoption from the stream API.
This proposal should have no performance impact.
Storing the append mode inside of the stream brings the stream API inline with
open which developers will already be familiar
Core tests will be written to exercise the new API including tests with multiple threads.
The existing fs_test suite used by memfs already includes append related tests which should catch any potential regressions during the migration.
The Zircon stream documentation will be updated with the changes to the API.
Drawbacks, alternatives, and unknowns
Alternative: Store the append mode in fdio
Store the append mode of the connection directly in fdio and use the stream API as is.
Storing the append mode in the stream is preferred because it matches how appends work in POSIX.
Filesystems that support streams will typically implement
Seek by dispatching the requests to a
stream internally. Each connection already keeps track of its append mode for
GetFlags requests which makes using
ZX_STREAM_APPEND forces the filesystem to keep the append mode of the
connection and the append mode of the stream in sync, which is not difficult.
Reducing the API surface area and matching POSIX is preferred over keeping