Pigweed
C/C++ API Reference
|
Public Types | |
enum | Whence : uint8_t { kBeginning = 0b001 , kCurrent = 0b010 , kEnd = 0b100 } |
Positions from which to seek. More... | |
Public Member Functions | |
constexpr bool | readable () const |
constexpr bool | writable () const |
constexpr bool | seekable () const |
constexpr bool | seekable (Whence origin) const |
True if the stream supports seeking from the specified origin. | |
Result< ByteSpan > | Read (ByteSpan dest) |
Result< ByteSpan > | Read (void *dest, size_t size_bytes) |
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. | |
Result< ByteSpan > | ReadExact (ByteSpan const buffer) |
Status | Write (ConstByteSpan data) |
Status | Write (const void *data, size_t size_bytes) |
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. | |
Status | Write (const std::byte b) |
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. | |
Status | Seek (ptrdiff_t offset, Whence origin=kBeginning) |
size_t | Tell () |
size_t | ConservativeReadLimit () const |
size_t | ConservativeWriteLimit () const |
Static Public Attributes | |
static constexpr size_t | kUnlimited = std::numeric_limits<size_t>::max() |
Value returned from read/write limit if unlimited. | |
static constexpr size_t | kUnknownPosition = std::numeric_limits<size_t>::max() |
Returned by Tell() if getting the position is not supported. | |
Protected Types | |
enum class | LimitType : bool { kRead , kWrite } |
Private Member Functions | |
virtual StatusWithSize | DoRead (ByteSpan destination)=0 |
Virtual Read() function implemented by derived classes. | |
virtual Status | DoWrite (ConstByteSpan data)=0 |
Virtual Write() function implemented by derived classes. | |
virtual Status | DoSeek (ptrdiff_t offset, Whence origin)=0 |
Virtual Seek() function implemented by derived classes. | |
virtual size_t | DoTell () |
virtual size_t | ConservativeLimit (LimitType limit_type) const |
A generic stream that may support reading, writing, and seeking, but makes no guarantees about whether any operations are supported. Unsupported functions return Status::Unimplemented() Stream serves as the base for the Reader, Writer, and ReaderWriter interfaces.
Stream cannot be extended directly. Instead, work with one of the derived classes that explicitly supports the required functionality. Stream should almost never be used in APIs; accept a derived class with the required capabilities instead.
All Stream methods are blocking. They return when the requested operation completes.
enum pw::stream::Stream::Whence : uint8_t |
Positions from which to seek.
|
inlineprivatevirtual |
Virtual function optionally implemented by derived classes that is used for ConservativeReadLimit() and ConservativeWriteLimit().
The default implementation returns kUnlimited or 0
depending on whether the stream is readable/writable.
Reimplemented in pw::stream::LimitedStreamWriter, and pw::multibuf::Stream.
|
inline |
Liklely (not guaranteed) minimum bytes available to read at this time. This number is advisory and not guaranteed to read full number of requested bytes or without a RESOURCE_EXHAUSTED
or OUT_OF_RANGE
. As Reader processes/handles/receives enqueued data or other contexts read data this number can go up or down for some Readers.
zero | if, in the current state, Read() would not return OkStatus(). |
kUnlimited | if the implementation imposes no limits on read sizes. |
|
inline |
Likely (not guaranteed) minimum bytes available to write at this time. This number is advisory and not guaranteed to write without a RESOURCE_EXHAUSTED
or OUT_OF_RANGE
. As Writer processes/handles enqueued of other contexts write data this number can go up or down for some Writers. Returns zero if, in the current state, Write() would not return OkStatus().
Returns kUnlimited if the implementation has no limits on write sizes.
|
privatepure virtual |
Virtual Read() function implemented by derived classes.
Implemented in pw::trace::TraceBufferReader, pw::stream::UartStreamLinux, pw::multibuf::Stream, pw::uart::UartStream, and pw::stream::Writer.
Virtual Seek() function implemented by derived classes.
Implemented in pw::multibuf::Stream, pw::stream::NonSeekableReader, pw::stream::NonSeekableWriter, and pw::stream::NonSeekableReaderWriter.
|
inlineprivatevirtual |
Virtual Tell() function optionally implemented by derived classes. The default implementation always returns kUnknownPosition.
Reimplemented in pw::multibuf::Stream.
|
privatepure virtual |
Virtual Write() function implemented by derived classes.
Implemented in pw::multibuf::Stream, pw::stream::LimitedStreamWriter, pw::stream::UartStreamLinux, pw::uart::UartStream, and pw::stream::Reader.
|
inline |
Reads data from the stream into the provided buffer, if supported. As many bytes as are available up to the buffer size are copied into the buffer. Remaining bytes may by read in subsequent calls. If any number of bytes are read returns OK with a span of the bytes read.
If the reader has been exhausted and is and can no longer read additional bytes it will return OUT_OF_RANGE
. This is similar to end-of-file (EOF). Read will only return OUT_OF_RANGE
if ConservativeReadLimit() is and will remain zero. A Read operation that is successful and also exhausts the reader returns OK, with all following calls returning OUT_OF_RANGE
.
Derived classes should NOT try to override these public read methods. Instead, provide an implementation by overriding DoRead().
embed:rst:leading-asterisk * * .. pw-status-codes:: * * OK: Between 1 and ``dest.size_bytes()`` were successfully * read. Returns the span of read bytes. * * UNIMPLEMENTED: This stream does not support reading. * * FAILED_PRECONDITION: The Reader is not in state to read data. * * RESOURCE_EXHAUSTED: Unable to read any bytes at this time. No * bytes read. Try again once bytes become available. * * OUT_OF_RANGE: Reader has been exhausted, similar to EOF. No bytes * were read, no more will be read. * *
|
inlineconstexpr |
True | If reading is supported. |
False | If Read() returns UNIMPLEMENTED. |
|
inline |
Reads exactly the number of bytes requested into the provided buffer, if supported. Internally, the stream is read as many times as necessary to fill the destination buffer. If fewer bytes than requested are available, OUT_OF_RANGE
is returned.
Other errors may be returned, as documented on Read().
|
inline |
Changes the current position in the stream for both reading and writing, if supported.
Seeking to a negative offset is invalid. The behavior when seeking beyond the end of a stream is determined by the implementation. The implementation could fail with OUT_OF_RANGE or append bytes to the stream.
embed:rst:leading-asterisk * * .. pw-status-codes:: * * OK: Successfully updated the position. * * UNIMPLEMENTED: Seeking is not supported for this stream. * * OUT_OF_RANGE: Attempted to seek beyond the bounds of the * stream. The position is unchanged. * *
|
inlineconstexpr |
True | If the stream supports seeking. |
False | If the stream does not supports seeking. |
|
inline |
Returns the current position in the stream, if supported. The position is the offset from the beginning of the stream. Returns Stream::kUnknownPosition (size_t(-1)
) if the position is unknown.
Streams that support seeking from the beginning always support Tell(). Other streams may or may not support Tell().
|
inlineconstexpr |
True | If writing is supported. |
False | If Write() returns UNIMPLEMENTED. |
|
inline |
Writes data to this stream. Data is not guaranteed to be fully written out to final resting place on Write return.
If the writer is unable to fully accept the input data size it will abort the write and return RESOURCE_EXHAUSTED
.
If the writer has been exhausted and is and can no longer accept additional bytes it will return OUT_OF_RANGE
. This is similar to end-of-file (EOF). Write will only return OUT_OF_RANGE
if ConservativeWriteLimit() is and will remain zero. A Write operation that is successful and also exhausts the writer returns OK, with all following calls returning OUT_OF_RANGE
. When ConservativeWriteLimit() is greater than zero, a Write that is a number of bytes beyond what will exhaust the Write will abort and return RESOURCE_EXHAUSTED
rather than OUT_OF_RANGE because the writer is still able to write bytes.
Derived classes should NOT try to override the public Write methods. Instead, provide an implementation by overriding DoWrite().
embed:rst:leading-asterisk * * .. pw-status-codes:: * * OK: Data was successfully accepted by the stream. * * UNIMPLEMENTED: This stream does not support writing. * * FAILED_PRECONDITION: The writer is not in a state to accept data. * * RESOURCE_EXHAUSTED: The writer was unable to write all of requested * data at this time. No data was written. * * OUT_OF_RANGE: The Writer has been exhausted, similar to EOF. No * data was written; no more will be written. * *