blob: c2b92c64ea04b3e53710ccdc3c87279f2cb867a8 [file] [log] [blame]
// 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_