blob: 0382f7a4bd5922dda0277ba421d71c1079b6e7e4 [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 NET_THIRD_PARTY_QUIC_CORE_QUIC_PACKET_WRITER_H_
#define NET_THIRD_PARTY_QUIC_CORE_QUIC_PACKET_WRITER_H_
#include <cstddef>
#include "net/third_party/quic/core/quic_packets.h"
#include "net/third_party/quic/platform/api/quic_export.h"
#include "net/third_party/quic/platform/api/quic_ptr_util.h"
#include "net/third_party/quic/platform/api/quic_socket_address.h"
namespace quic {
struct WriteResult;
struct QUIC_EXPORT_PRIVATE PerPacketOptions {
virtual ~PerPacketOptions() {}
// Returns a heap-allocated copy of |this|.
//
// The subclass implementation of this method should look like this:
// return QuicMakeUnique<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;
// Specifies release time delay for this packet.
QuicTime::Delta release_time_delay = QuicTime::Delta::Zero();
};
// 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 QUIC_EXPORT_PRIVATE 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.
virtual WriteResult WritePacket(const char* buffer,
size_t buf_len,
const QuicIpAddress& self_address,
const QuicSocketAddress& peer_address,
PerPacketOptions* options) = 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;
// 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;
// PassThrough mode: Return nullptr.
//
// Batch mode:
// Return the starting address for the next packet's data. A minimum of
// kMaxPacketSize is guaranteed to be available from the returned address. If
// the internal buffer does not have enough space, 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|.
virtual char* 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, or an error status, if the underlying socket
// is blocked or returned an error while sending. Some packets may have been
// sent, packets not sent will stay in the internal buffer.
virtual WriteResult Flush() = 0;
};
} // namespace quic
#endif // NET_THIRD_PARTY_QUIC_CORE_QUIC_PACKET_WRITER_H_