| // Copyright 2013 The Chromium Authors. All rights reserved. |
| // Use of this source code is governed by a BSD-style license that can be |
| // found in the LICENSE file. |
| |
| #ifndef QUICHE_QUIC_CORE_QUIC_PACKET_WRITER_H_ |
| #define QUICHE_QUIC_CORE_QUIC_PACKET_WRITER_H_ |
| |
| #include <cstddef> |
| #include <optional> |
| #include <utility> |
| |
| #include "quiche/quic/core/quic_packets.h" |
| #include "quiche/quic/platform/api/quic_export.h" |
| #include "quiche/quic/platform/api/quic_ip_address.h" |
| #include "quiche/quic/platform/api/quic_socket_address.h" |
| |
| namespace quic { |
| |
| struct WriteResult; |
| |
| // This class allows a platform to pass instructions to an associated child of |
| // QuicWriter without intervening QUIC code understanding anything about its |
| // contents. |
| class QUICHE_EXPORT PerPacketOptions { |
| public: |
| virtual ~PerPacketOptions() {} |
| |
| // Returns a heap-allocated copy of |this|. |
| // |
| // The subclass implementation of this method should look like this: |
| // return std::make_unique<MyAwesomePerPacketOptions>(*this); |
| // |
| // This method is declared pure virtual in order to ensure the subclasses |
| // would not forget to override it. |
| virtual std::unique_ptr<PerPacketOptions> Clone() const = 0; |
| }; |
| |
| // The owner of QuicPacketWriter can pass control information via this struct. |
| struct QUICHE_EXPORT QuicPacketWriterParams { |
| // Specifies ideal release time delay for this packet. |
| QuicTime::Delta release_time_delay = QuicTime::Delta::Zero(); |
| // Whether it is allowed to send this packet without |release_time_delay|. |
| bool allow_burst = false; |
| // ECN codepoint to use when sending this packet. |
| QuicEcnCodepoint ecn_codepoint = ECN_NOT_ECT; |
| }; |
| |
| // An interface between writers and the entity managing the |
| // socket (in our case the QuicDispatcher). This allows the Dispatcher to |
| // control writes, and manage any writers who end up write blocked. |
| // A concrete writer works in one of the two modes: |
| // - PassThrough mode. This is the default mode. Caller calls WritePacket with |
| // caller-allocated packet buffer. Unless the writer is blocked, each call to |
| // WritePacket triggers a write using the underlying socket API. |
| // |
| // - Batch mode. In this mode, a call to WritePacket may not cause a packet to |
| // be sent using the underlying socket API. Instead, multiple packets are |
| // saved in the writer's internal buffer until they are flushed. The flush can |
| // be explicit, by calling Flush, or implicit, e.g. by calling |
| // WritePacket when the internal buffer is near full. |
| // |
| // Buffer management: |
| // In Batch mode, a writer manages an internal buffer, which is large enough to |
| // hold multiple packets' data. If the caller calls WritePacket with a |
| // caller-allocated packet buffer, the writer will memcpy the buffer into the |
| // internal buffer. Caller can also avoid this memcpy by: |
| // 1. Call GetNextWriteLocation to get a pointer P into the internal buffer. |
| // 2. Serialize the packet directly to P. |
| // 3. Call WritePacket with P as the |buffer|. |
| class QUICHE_EXPORT QuicPacketWriter { |
| public: |
| virtual ~QuicPacketWriter() {} |
| |
| // PassThrough mode: |
| // Sends the packet out to the peer, with some optional per-packet options. |
| // If the write succeeded, the result's status is WRITE_STATUS_OK and |
| // bytes_written is populated. If the write failed, the result's status is |
| // WRITE_STATUS_BLOCKED or WRITE_STATUS_ERROR and error_code is populated. |
| // |
| // Batch mode: |
| // If the writer is blocked, return WRITE_STATUS_BLOCKED immediately. |
| // If the packet can be batched with other buffered packets, save the packet |
| // to the internal buffer. |
| // If the packet can not be batched, or the internal buffer is near full after |
| // it is buffered, the internal buffer is flushed to free up space. |
| // Return WriteResult(WRITE_STATUS_OK, <bytes_flushed>) on success. When |
| // <bytes_flushed> is zero, it means the packet is buffered and not flushed. |
| // Return WRITE_STATUS_BLOCKED if the packet is not buffered and the socket is |
| // blocked while flushing. |
| // Otherwise return an error status. |
| // |
| // Options must be either null, or created for the particular QuicPacketWriter |
| // implementation. Options may be ignored, depending on the implementation. |
| // |
| // Some comment about memory management if |buffer| was previously acquired |
| // by a call to "GetNextWriteLocation()": |
| // |
| // a) When WRITE_STATUS_OK is returned, the caller expects the writer owns the |
| // packet buffers and they will be released when the write finishes. |
| // |
| // b) When this function returns any status >= WRITE_STATUS_ERROR, the caller |
| // expects the writer releases the buffer (if needed) before the function |
| // returns. |
| // |
| // c) When WRITE_STATUS_BLOCKED is returned, the caller makes a copy of the |
| // buffer and will retry after unblock, so if |payload| is allocated from |
| // GetNextWriteLocation(), it |
| // 1) needs to be released before return, and |
| // 2) the content of |payload| should not change after return. |
| // |
| // d) When WRITE_STATUS_BLOCKED_DATA_BUFFERED is returned, the caller expects |
| // 1) the writer owns the packet buffers, and 2) the writer will re-send the |
| // packet when it unblocks. |
| virtual WriteResult WritePacket(const char* buffer, size_t buf_len, |
| const QuicIpAddress& self_address, |
| const QuicSocketAddress& peer_address, |
| PerPacketOptions* options, |
| const QuicPacketWriterParams& params) = 0; |
| |
| // Returns true if the network socket is not writable. |
| virtual bool IsWriteBlocked() const = 0; |
| |
| // Records that the socket has become writable, for example when an EPOLLOUT |
| // is received or an asynchronous write completes. |
| virtual void SetWritable() = 0; |
| |
| // The error code used by the writer to indicate that the write failed due to |
| // supplied packet being too big. This is equivalent to returning |
| // WRITE_STATUS_MSG_TOO_BIG as a status. |
| virtual std::optional<int> MessageTooBigErrorCode() const = 0; |
| |
| // Returns the maximum size of the packet which can be written using this |
| // writer for the supplied peer address. This size may actually exceed the |
| // size of a valid QUIC packet. |
| virtual QuicByteCount GetMaxPacketSize( |
| const QuicSocketAddress& peer_address) const = 0; |
| |
| // Returns true if the socket supports release timestamp. |
| virtual bool SupportsReleaseTime() const = 0; |
| |
| // True=Batch mode. False=PassThrough mode. |
| virtual bool IsBatchMode() const = 0; |
| |
| // Returns true if the writer will mark ECN on packets it writes. |
| virtual bool SupportsEcn() const = 0; |
| |
| // PassThrough mode: Return {nullptr, nullptr} |
| // |
| // Batch mode: |
| // Return the QuicPacketBuffer for the next packet. A minimum of |
| // kMaxOutgoingPacketSize is guaranteed to be available from the returned |
| // address. If the internal buffer does not have enough space, |
| // {nullptr, nullptr} is returned. All arguments should be identical to the |
| // follow-up call to |WritePacket|, they are here to allow advanced packet |
| // memory management in packet writers, e.g. one packet buffer pool per |
| // |peer_address|. |
| // |
| // If QuicPacketBuffer.release_buffer is !nullptr, it should be called iff |
| // the caller does not call WritePacket for the returned buffer. |
| virtual QuicPacketBuffer GetNextWriteLocation( |
| const QuicIpAddress& self_address, |
| const QuicSocketAddress& peer_address) = 0; |
| |
| // PassThrough mode: Return WriteResult(WRITE_STATUS_OK, 0). |
| // |
| // Batch mode: |
| // Try send all buffered packets. |
| // - Return WriteResult(WRITE_STATUS_OK, <bytes_flushed>) if all buffered |
| // packets were sent successfully. |
| // - Return WRITE_STATUS_BLOCKED if the underlying socket is blocked while |
| // sending. Some packets may have been sent, packets not sent will stay in |
| // the internal buffer. |
| // - Return a status >= WRITE_STATUS_ERROR if an error was encuontered while |
| // sending. As this is not a re-tryable error, any batched packets which |
| // were on memory acquired via GetNextWriteLocation() should be released and |
| // the batch should be dropped. |
| virtual WriteResult Flush() = 0; |
| }; |
| |
| } // namespace quic |
| |
| #endif // QUICHE_QUIC_CORE_QUIC_PACKET_WRITER_H_ |