[syncstream.syncbuf] - C++17 → C++20

Files changed (1) hide show

tmp/tmpspkgbnv7/{from.md → to.md} +210 -0

tmp/tmpspkgbnv7/{from.md → to.md} RENAMED Viewed

	@@ -0,0 +1,210 @@

+### Class template `basic_syncbuf` <a id="syncstream.syncbuf">[[syncstream.syncbuf]]</a>
+#### Overview <a id="syncstream.syncbuf.overview">[[syncstream.syncbuf.overview]]</a>
+``` cpp
+namespace std {
+  template<class charT, class traits = char_traits<charT>, class Allocator = allocator<charT>>
+  class basic_syncbuf : public basic_streambuf<charT, traits> {
+  public:
+    using char_type      = charT;
+    using int_type       = typename traits::int_type;
+    using pos_type       = typename traits::pos_type;
+    using off_type       = typename traits::off_type;
+    using traits_type    = traits;
+    using allocator_type = Allocator;
+    using streambuf_type = basic_streambuf<charT, traits>;
+    // [syncstream.syncbuf.cons], construction and destruction
+    basic_syncbuf()
+      : basic_syncbuf(nullptr) {}
+    explicit basic_syncbuf(streambuf_type* obuf)
+      : basic_syncbuf(obuf, Allocator()) {}
+    basic_syncbuf(streambuf_type*, const Allocator&);
+    basic_syncbuf(basic_syncbuf&&);
+    ~basic_syncbuf();
+    // [syncstream.syncbuf.assign], assignment and swap
+    basic_syncbuf& operator=(basic_syncbuf&&);
+    void swap(basic_syncbuf&);
+    // [syncstream.syncbuf.members], member functions
+    bool emit();
+    streambuf_type* get_wrapped() const noexcept;
+    allocator_type get_allocator() const noexcept;
+    void set_emit_on_sync(bool) noexcept;
+  protected:
+    // [syncstream.syncbuf.virtuals], overridden virtual functions
+    int sync() override;
+  private:
+    streambuf_type* wrapped;    // exposition only
+    bool emit_on_sync{};        // exposition only
+  };
+  // [syncstream.syncbuf.special], specialized algorithms
+  template<class charT, class traits, class Allocator>
+    void swap(basic_syncbuf<charT, traits, Allocator>&,
+              basic_syncbuf<charT, traits, Allocator>&);
+}
+```
+Class template `basic_syncbuf` stores character data written to it,
+known as the associated output, into internal buffers allocated using
+the object’s allocator. The associated output is transferred to the
+wrapped stream buffer object `*wrapped` when `emit()` is called or when
+the `basic_syncbuf` object is destroyed. Such transfers are atomic with
+respect to transfers by other `basic_syncbuf` objects with the same
+wrapped stream buffer object.
+#### Construction and destruction <a id="syncstream.syncbuf.cons">[[syncstream.syncbuf.cons]]</a>
+``` cpp
+basic_syncbuf(streambuf_type* obuf, const Allocator& allocator);
+```
+*Effects:* Sets `wrapped` to `obuf`.
+*Remarks:* A copy of `allocator` is used to allocate memory for internal
+buffers holding the associated output.
+*Throws:* Nothing unless an exception is thrown by the construction of a
+mutex or by memory allocation.
+*Ensures:* `get_wrapped() == obuf` and `get_allocator() == allocator`
+are `true`.
+``` cpp
+basic_syncbuf(basic_syncbuf&& other);
+```
+*Ensures:* The value returned by `this->get_wrapped()` is the value
+returned by `other.get_wrapped()` prior to calling this constructor.
+Output stored in `other` prior to calling this constructor will be
+stored in `*this` afterwards.
+`other.rdbuf()->pbase() == other.rdbuf()->pptr()` and
+`other.get_wrapped() == nullptr` are `true`.
+*Remarks:* This constructor disassociates `other` from its wrapped
+stream buffer, ensuring destruction of `other` produces no output.
+``` cpp
+~basic_syncbuf();
+```
+*Effects:* Calls `emit()`.
+*Throws:* Nothing. If an exception is thrown from `emit()`, the
+destructor catches and ignores that exception.
+#### Assignment and swap <a id="syncstream.syncbuf.assign">[[syncstream.syncbuf.assign]]</a>
+``` cpp
+basic_syncbuf& operator=(basic_syncbuf&& rhs) noexcept;
+```
+*Effects:* Calls `emit()` then move assigns from `rhs`. After the move
+assignment `*this` has the observable state it would have had if it had
+been move constructed from `rhs` [[syncstream.syncbuf.cons]].
+*Returns:* `*this`.
+*Ensures:*
+- `rhs.get_wrapped() == nullptr` is `true`.
+- `this->get_allocator() == rhs.get_allocator()` is `true` when
+  ``` cpp
+  allocator_traits<Allocator>::propagate_on_container_move_assignment::value
+  ```
+  is `true`; otherwise, the allocator is unchanged.
+*Remarks:* This assignment operator disassociates `rhs` from its wrapped
+stream buffer, ensuring destruction of `rhs` produces no output.
+``` cpp
+void swap(basic_syncbuf& other) noexcept;
+```
+*Preconditions:* Either
+`allocator_traits<Allocator>::propagate_on_container_swap::value` is
+`true` or `this->get_allocator() == other.get_allocator()` is `true`.
+*Effects:* Exchanges the state of `*this` and `other`.
+#### Member functions <a id="syncstream.syncbuf.members">[[syncstream.syncbuf.members]]</a>
+``` cpp
+bool emit();
+```
+*Effects:* Atomically transfers the associated output of `*this` to the
+stream buffer `*wrapped`, so that it appears in the output stream as a
+contiguous sequence of characters. `wrapped->pubsync()` is called if and
+only if a call was made to `sync()` since the most recent call to
+`emit()`, if any.
+*Returns:* `true` if all of the following conditions hold; otherwise
+`false`:
+- `wrapped == nullptr` is `false`.
+- All of the characters in the associated output were successfully
+  transferred.
+- The call to `wrapped->pubsync()` (if any) succeeded.
+*Ensures:* On success, the associated output is empty.
+*Synchronization:* All `emit()` calls transferring characters to the
+same stream buffer object appear to execute in a total order consistent
+with the “happens before” relation [[intro.races]], where each `emit()`
+call synchronizes with subsequent `emit()` calls in that total order.
+*Remarks:* May call member functions of `wrapped` while holding a lock
+uniquely associated with `wrapped`.
+``` cpp
+streambuf_type* get_wrapped() const noexcept;
+```
+*Returns:* `wrapped`.
+``` cpp
+allocator_type get_allocator() const noexcept;
+```
+*Returns:* A copy of the allocator that was set in the constructor or
+assignment operator.
+``` cpp
+void set_emit_on_sync(bool b) noexcept;
+```
+*Effects:* `emit_on_sync = b`.
+#### Overridden virtual functions <a id="syncstream.syncbuf.virtuals">[[syncstream.syncbuf.virtuals]]</a>
+``` cpp
+int sync() override;
+```
+*Effects:* Records that the wrapped stream buffer is to be flushed.
+Then, if `emit_on_sync` is `true`, calls `emit()`.
+[*Note 1*: If `emit_on_sync` is `false`, the actual flush is delayed
+until a call to `emit()`. — *end note*]
+*Returns:* If `emit()` was called and returned `false`, returns `-1`;
+otherwise `0`.
+#### Specialized algorithms <a id="syncstream.syncbuf.special">[[syncstream.syncbuf.special]]</a>
+``` cpp
+template<class charT, class traits, class Allocator>
+  void swap(basic_syncbuf<charT, traits, Allocator>& a,
+            basic_syncbuf<charT, traits, Allocator>& b) noexcept;
+```
+*Effects:* Equivalent to `a.swap(b)`.

Diff to HTML by rtfpessoa