 |
C/C++ API Reference
|
Writer for a multi-producer, single consumer stream.
This class has a default constructor that only produces disconnected writers. To connect writers, use CreateMpscStream(). Additional connected writers can be created by copying an existing one.
Each thread should have its own dedicated writer. This class is thread-safe with respect to the reader, but not with respect to itself. In particular, attempting to call Write() concurrently on different threads may cause result in a failure.
Classes | |
| struct | Request |
Public Types | |
| using | duration = std::optional< chrono::SystemClock::duration > |
 Public Types inherited from pw::stream::Stream | |
| enum | Whence : uint8_t { kBeginning = 0b001 , kCurrent = 0b010 , kEnd = 0b100 } |
| Positions from which to seek. More... | |
Public Member Functions | |
| MpscWriter (const MpscWriter &other) | |
| MpscWriter & | operator= (const MpscWriter &other) |
| MpscWriter (MpscWriter &&other) | |
| MpscWriter & | operator= (MpscWriter &&other) |
| bool | connected () const |
| Returns whether this object is connected to a reader. | |
| size_t | last_write () const |
Indicates how much data was sent in the last call to Write(). | |
| const duration & | timeout () const |
Returns the optional maximum time elapsed before a Write() fails. | |
| void | SetTimeout (const duration &timeout) |
| void | SetLimit (size_t limit) |
| void | Close () |
| Public Member Functions inherited from pw::stream::Stream | |
| 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 |
Private Member Functions | |
| size_t | ConservativeLimit (LimitType type) const override |
| Status | DoWrite (ConstByteSpan data) override |
| Virtual Write() function implemented by derived classes. | |
Friends | |
| void | CreateMpscStream (MpscReader &, MpscWriter &) |
Additional Inherited Members | |
| Static Public Attributes inherited from pw::stream::Stream | |
| 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 inherited from pw::stream::Stream | |
| enum class | LimitType : bool { kRead , kWrite } |
| Protected Member Functions inherited from pw::containers::future::IntrusiveList< T >::Item | |
| constexpr | Item ()=default |
| void pw::stream::MpscWriter::Close | ( | ) |
Disconnects this writer from its reader.
This method does nothing if the writer is not connected.
|
overrideprivatevirtual |
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 from pw::stream::Stream.
|
overrideprivatevirtual |
Virtual Write() function implemented by derived classes.
This method is not thread-safe with respect to itself. If multiple threads attempt to write concurrently using the same writer, those calls may fail. Instead, each thread should have its own writer.
Write() on this object. Implements pw::stream::Stream.
| void pw::stream::MpscWriter::SetLimit | ( | size_t | limit | ) |
Sets the maximum amount that can be written by this writer.
By default, writers can write an unlimited amount of data. This method can be used to set a limit, or remove it by providing a value of Stream::kUnlimited.
If a limit is set, the writer will automatically close once it has written that much data. The current number of bytes remaining until the limit is reached can be retrieved using ConservativeWriteLimit().
| [in] | limit | The maximum amount that can be written by this writer. |
| void pw::stream::MpscWriter::SetTimeout | ( | const duration & | timeout | ) |
Set the timeout for writing to this stream.
After setting a timeout, if the given duration elapses while making a call to Write(),
embed:rst:inline :c:enumerator:`RESOURCE_EXHAUSTED`
will be returned. If desired, a timeout should be set before calling Write(). Setting a timeout when a writer is awaiting notification from a reader will not affect the duration of that wait.
Note that setting a write timeout makes partial writes possible. For example, if a call to Write() of some length corresponds to 2 calls to Read() of half that length with an sufficient delay between the calls will result in the first half being written and read, but not the second. This differs from Stream::Write() which stipulates that no data is written on failure. If this happens, the length of the data written can be retrieved using last_write().
Generally, callers should use one of three approaches:
last_write() to resend data.| [in] | timeout | The duration to wait before returning an error. |
|
friend |
Creates a multi-producer, single consumer stream.
This method creates a stream by associating a reader and writer. Both are reset before being connected. This is the only way to connect a reader. Additional writers may be connected by copying the given writer after it is connected.
This method is thread-safe with respect to other MpscReader and MpscWriter methods. It is not thread-safe with respect to itself, i.e. callers must not make concurrent calls to CreateMpscStream() from different threads with the same objects.
| [out] | reader | The reader to connect. |
| [out] | writer | The writer to connect. |
1.9.6