folly::AsyncTransport

Synopsis

Declared in <folly/io/async/AsyncTransport.h>

class AsyncTransport
    : public DelayedDestruction
    , public AsyncSocketBase
    , public AsyncReader
    , public AsyncWriter

Description

This class provides an API to for asynchronously waiting for data on a streaming transport, and for asynchronously sending data.

The APIs for reading and writing are intentionally asymmetric. Waiting for data to read is a persistent API: a callback is installed, and is notified whenever new data is available. It continues to be notified of new events until it is uninstalled.

AsyncTransport does not provide read timeout functionality, because it typically cannot determine when the timeout should be active. Generally, a timeout should only be enabled when processing is blocked waiting on data from the remote endpoint. For server‐side applications, the timeout should not be active if the server is currently processing one or more outstanding requests on this transport. For client‐side applications, the timeout should not be active if there are no requests pending on the transport. Additionally, if a client has multiple pending requests, it will ususally want a separate timeout for each request, rather than a single read timeout.

The write API is fairly intuitive: a user can request to send a block of data, and a callback will be informed once the entire block has been transferred to the kernel, or on error. AsyncTransport does provide a send timeout, since most callers want to give up if the remote end stops responding and no further progress can be made sending the data.

Base Classes

Name

Description

DelayedDestruction

DelayedDestruction is a helper class to ensure objects are not deleted while they still have functions executing in a higher stack frame.

AsyncSocketBase

Base interface for asynchronous sockets bound to an event base.

AsyncReader

Interface for the read side of an asynchronous transport.

AsyncWriter

Interface for the write side of an asynchronous transport.

Types

Name

Description

BufferCallback

Callback class to signal changes in the transport's internal buffers.

Destructor

Helper class to allow DelayedDestruction classes to be used with std::shared_ptr.

DestructorGuard

Classes should create a DestructorGuard object on the stack in any function that may invoke callback functions.

IntrusivePtr

This smart pointer is a convenient way to manage a concrete DelayedDestructorBase child. It can replace the equivalent raw pointer and provide automatic memory management.

RXZerocopyParams

Parameters controlling receive‐side zero‐copy.

ReadCallback

Callback interface used to receive data read from the transport.

ReleaseIOBufCallback

Callback invoked to release ownership of an IOBuf after a write.

ReplaySafetyCallback

Callback class to signal when a transport that did not have replay protection gains replay protection. This is needed for 0‐RTT security protocols.

WriteCallback

Callback interface used to report the result of a write.

Type Aliases

Name

Description

UniquePtr

Owning pointer that uses the DelayedDestruction Destructor.

ZeroCopyEnableFunc

Predicate deciding whether a given buffer should use zero‐copy writes.

Member Functions

Name

Description

operator= [deleted]

Deleted copy assignment operator.

attachEventBase [virtual]

Attach the transport to a EventBase.

close [virtual]

Close the transport.

closeNow [virtual]

Close the transport immediately.

closeWithReset [virtual]

Reset the transport immediately.

connecting [virtual]

Determine if transport is connected to the endpoint

destroy [virtual]

destroy() requests destruction of the object.

detachEventBase [virtual]

Detach the transport from its EventBase.

dropPeerCertificate [virtual]

Hints to transport implementations that the associated certificate is no longer required by the application. The transport implementation may choose to free up resources associated with the peer certificate.

dropSelfCertificate [virtual]

Hints to transport implementations that the associated certificate is no longer required by the application. The transport implementation may choose to free up resources associated with the self certificate.

error [virtual]

Determine if an error has occurred with this transport.

getAddress [virtual]

Store the local address of this transport in the given SocketAddress.

getAllocatedBytesBuffered [virtual]

Return the number of allocated bytes buffered to be written later.

getAppBytesBuffered [virtual]

Calculates the total number of bytes that are currently buffered in the transport to be written later.

getAppBytesReceived [virtual]

Return the number of application‐level bytes received.

getAppBytesWritten [virtual]

Return the number of application‐level bytes written.

getApplicationProtocol [virtual]

Return the application protocol being used by the underlying transport protocol. This is useful for transports which are used to tunnel other protocols.

getDestroyPending

Returns whether destruction has been requested but deferred.

getEventBase [virtual]

Returns the event base this socket is attached to.

getExportedKeyingMaterial [virtual]

Produce exported keying material for this transport.

getLocalAddress

getLocalAddress overloads

getNapiId [virtual]

Return SO_INCOMING_NAPI_ID for this transport. For socket transports, this is associated with the NAPI instance/receive queue. For other transports, it is not defined.

getPeerAddress

Get the address of the remote endpoint to which this transport is connected.

getPeerCertificate [virtual]

Get the peer certificate information if any

getRXZeroCopy [virtual]

Return whether receive‐side zero‐copy is enabled.

getRawBytesBuffered [virtual]

Return the number of raw bytes buffered to be written later.

getRawBytesReceived [virtual]

Return the number of raw bytes received from the underlying transport.

getRawBytesWritten [virtual]

Return the number of raw bytes written to the underlying transport.

getReadCallback [virtual]

Return the currently installed read callback.

getSecurityProtocol [virtual]

Returns the name of the security protocol being used.

getSelfCertificate [virtual]

Get the certificate information of this transport, if any

getSendTimeout [virtual]

Get the send timeout.

getUnderlyingTransport

getUnderlyingTransport overloads

getWrappedTransport [virtual]

AsyncTransports may wrap other AsyncTransport. This returns the transport that is wrapped. It returns nullptr if there is no wrapped transport.

getWrappingTransport

getWrappingTransport overloads

getZeroCopy [virtual]

Return whether zero‐copy writes are enabled.

good [virtual]

Determine if transport is open and ready to read or write.

isDetachable [virtual]

Determine if the transport can be detached.

isEorTrackingEnabled [virtual]

Return whether end‐of‐record tracking is enabled.

isPending [virtual]

Determine if the there is pending data on the transport.

isReplaySafe [virtual]

False if the transport does not have replay protection, but will in the future.

readable [virtual]

Determine if the transport is readable or not.

setEorTracking [virtual]

Enable or disable end‐of‐record tracking.

setRXZeroCopy [virtual]

Enable or disable receive‐side zero‐copy using the given parameters.

setReadCB [virtual]

Install the read callback that will receive read events.

setReplaySafetyCallback [virtual]

Set the ReplaySafeCallback on this transport.

setSendTimeout [virtual]

Set the send timeout.

setZeroCopy [virtual]

Enable or disable zero‐copy writes.

setZeroCopyEnableFunc [virtual]

Set the predicate deciding when zero‐copy writes are used.

setZeroCopyEnableThreshold [virtual]

Set the minimum write size, in bytes, for using zero‐copy writes.

shutdownWrite [virtual]

Perform a half‐shutdown of the write side of the transport.

shutdownWriteNow [virtual]

Perform a half‐shutdown of the write side of the transport.

takePreReceivedData [virtual]

Take any data received before a read callback was installed.

tryExchangeUnderlyingTransport

Exchange the underlying transport of type T with the given one.

tryExchangeWrappedTransport [virtual]

Exchange the directly wrapped transport with the given one.

writable [virtual]

Determine if the transport is writable or not.

write [virtual]

If you supply a non‐null WriteCallback, exactly one of writeSuccess() or writeErr() will be invoked when the write completes. If you supply the same WriteCallback object for multiple write() calls, it will be invoked exactly once per call. The only way to cancel outstanding write requests is to close the socket (e.g., with closeNow() or shutdownWriteNow()). When closing the socket this way, writeErr() will still be invoked once for each outstanding write operation.

writeChain [virtual]

If you supply a non‐null WriteCallback, exactly one of writeSuccess() or writeErr() will be invoked when the write completes. If you supply the same WriteCallback object for multiple write() calls, it will be invoked exactly once per call. The only way to cancel outstanding write requests is to close the socket (e.g., with closeNow() or shutdownWriteNow()). When closing the socket this way, writeErr() will still be invoked once for each outstanding write operation.

writev [virtual]

If you supply a non‐null WriteCallback, exactly one of writeSuccess() or writeErr() will be invoked when the write completes. If you supply the same WriteCallback object for multiple write() calls, it will be invoked exactly once per call. The only way to cancel outstanding write requests is to close the socket (e.g., with closeNow() or shutdownWriteNow()). When closing the socket this way, writeErr() will still be invoked once for each outstanding write operation.