Class NetworkBackend

Inheritance Relationships

Derived Types

Class Documentation

class NetworkBackend

Abstract base class for network backends.

Defines the interface for all implementations of network backends. The backend is responsible for managing the network connections and sending and receiving data.

Use the factory method create to create a network backend object.

Invokes the following callbacks:

  • on_data_cb: When data is received. The data is passed as a span of const uint8_t

  • on_connection_established_cb: When a connection is established. Provides the address of the endpoint

  • on_connection_closed_cb: When a connection is closed. Provides the address of the endpoint and for zero-copy sends the keys of the pending send operations (otherwise empty)

  • on_connection_refused_cb: When a connection is refused. Provides the address of the endpoint

  • on_send_completed_cb: When a send operation is completed. Provides the address of the endpoint and the key of the send operation

Subclassed by netio3::asyncmsg::BackendAsyncmsg, netio3::libfabric::BackendLibfabric

Public Functions

NetworkBackend(NetworkConfig config, std::shared_ptr<BaseEventLoop> evloop)

Constructs a NetworkBackend object with the specified network configuration and event loop.

The network configuration decides whether RDMA or TCP is used. It also decides whether the backend provides thread safety or not. If the backend is not thread safe, it is the user’s responsibility to ensure that only one thread interacts with the backend. The configuration also contains the callbacks for connection events, send completions and data reception. The event loop must be an implementation of the BaseEventLoop interface. The event loop is used to register all kinds of asynchronous events.

Parameters:

  • config – The network configuration

  • evloop – The event loop to use for network operations

virtual ~NetworkBackend() = default
NetworkBackend(const NetworkBackend&) = delete
NetworkBackend(NetworkBackend&&) = delete
NetworkBackend &operator=(const NetworkBackend&) = delete
NetworkBackend &operator=(NetworkBackend&&) = delete
virtual void open_send_endpoint(const EndPointAddress &address, const ConnectionParameters &connection_params) = 0

Opens a send endpoint for the specified address with the given connection parameters.

Parameters:

  • address – The address of the endpoint to open

  • connection_params – The connection parameters for the endpoint

Throws:

  • InvalidEndpointAddress – if the endpoint address is invalid

  • FailedOpenSendEndpoint – if the send endpoint could not be opened

  • SendEndpointAlreadyExists – if the send endpoint already exists

virtual EndPointAddress open_listen_endpoint(const EndPointAddress &address, const ConnectionParametersRecv &connection_params) = 0

Opens a listen endpoint for the specified address with the given connection parameters.

Should accept all incoming connections. The connection parameters are passed to the spawned receive sockets. If port 0 was passed in, it should return the port number that was used to open the listen endpoint.

Parameters:

  • address – The address of the endpoint to open

  • connection_params – The connection parameters for the endpoint

Throws:

  • InvalidEndpointAddress – if the endpoint address is invalid

  • ListenEndpointAlreadyExists – If already requested to listen on this address and port

  • FailedOpenListenEndpoint – if the listen endpoint could not be opened

Returns:

The actual address the server is listening on

virtual void close_send_endpoint(const EndPointAddress &address) = 0

Closes the send endpoint for the specified address.

May enqueue the endpoint to be closed by the event loop for thread synchronization purposes.

Parameters:

address – The address of the endpoint to close

Throws:

  • InvalidEndpointAddress – if the endpoint address is invalid

  • UnknownSendEndpoint – if the send endpoint does not exist

  • FailedCloseSendEndpoint – if closing the send socket failed

virtual void close_listen_endpoint(const EndPointAddress &address) = 0

Closes the listen endpoint for the specified address.

Shall also close all receive sockets that were spawned by this listen socket.

May enqueue the endpoint to be closed by the event loop for thread synchronization purposes.

Parameters:

address – The address of the endpoint to close

Throws:

  • InvalidEndpointAddress – if the endpoint address is invalid

  • UnknownListenEndpoint – if the listen endpoint does not exist

  • FailedCloseListenEndpoint – if closing the listen socket failed

virtual NetioStatus send_data(const EndPointAddress &address, std::span<std::uint8_t> data, std::span<const std::uint8_t> header_data, std::uint64_t key) = 0

Sends data to the specified address in zero-copy mode.

The data shall not be copied but sent directly. The key will be provided on the on_send_completed callback to the user.

Header data is prepended to the actual data and sent together with it.

Parameters:

  • address – The address to send the data to

  • data – The data to send

  • header_data – User data to be added to the header

  • key – Key to be returned in on_send_completed callback

Throws:

  • InvalidEndpointAddress – If the address is invalid

  • UnknownSendEndpoint – No connection was opened on this endpoint

Returns:

The status of the send operation

virtual NetioStatus send_data(const EndPointAddress &address, std::span<const iovec> iov, std::span<const std::uint8_t> header_data, std::uint64_t key) = 0

Sends data to the specified address in zero-copy mode.

The data shall not be copied but sent directly. The key will be provided on the on_send_completed callback to the user.

Header data is prepended to the actual data and sent together with it.

Parameters:

  • address – The address to send the data to

  • iov – The iovec vector containing the data to send

  • header_data – User data to be added to the header

  • key – Key to be returned in on_send_completed callback

Throws:

  • InvalidEndpointAddress – If the address is invalid

  • UnknownSendEndpoint – No connection was opened on this endpoint

Returns:

The status of the send operation

virtual NetioStatus send_data_copy(const EndPointAddress &address, std::span<const std::uint8_t> data, std::span<const std::uint8_t> header_data, std::uint64_t key) = 0

Sends data to the specified address copying the data.

The data are copied and sent directly. The user does not have to make any guarantees about the lifetime of the data. The key will be provided on the on_send_completed callback to the user. The header data is prepended to the actual data and sent together with it.

Parameters:

  • address – The address to send the data to

  • data – The data to send

  • header_data – User data to be added to the header

  • key – Key to be returned in on_send_completed callback

Returns:

The status of the send operation

virtual NetioStatus send_data_copy(const EndPointAddress &address, std::span<const iovec> iov, std::span<const std::uint8_t> header_data, std::uint64_t key) = 0

Sends data to the specified address in zero-copy mode.

The data are copied and sent directly. The user does not have to make any guarantees about the lifetime of the data. The key will be provided on the on_send_completed callback to the user. The header data is prepended to the actual data and sent together with it.

Parameters:

  • address – The address to send the data to

  • iov – The iovec vector containing the data to send

  • header_data – User data to be added to the header

  • key – Key to be returned in on_send_completed callback

Returns:

The status of the send operation

virtual NetworkBuffer *get_buffer(const EndPointAddress &address) = 0

Retrieves a network buffer for the specified endpoint address.

Only works for endpoints that are opened for buffered sending. If no buffer is available returns a nullptr.

@important The user needs to check that the returned buffer is not null.

Parameters:

address – The address of the endpoint to retrieve the buffer for

Throws:

  • UnknownSendEndpoint – if the send endpoint does not exist

  • NoBuffersAllocated – if no buffers were allocated

Returns:

A pointer to the network buffer

virtual NetioStatus send_buffer(const EndPointAddress &address, NetworkBuffer *buffer) = 0

Sends a network buffer to the specified address.

This function sends the data buffer to the specified endpoint. A connection must be registered for this endpoint before sending data. If the buffer is not a buffer handed out through get_buffer FAILED is returned. The buffer will be returned to the connection after the send operation is completed.

Parameters:

  • address – The address to send the buffer to

  • buffer – The network buffer to send

Throws:

UnknownSendEndpoint – if the send endpoint does not exist

Returns:

The status of the send operation

virtual std::size_t get_num_available_buffers(const EndPointAddress &address) = 0

Retrieves the number of available buffers for the specified endpoint address.

Returns the mininum number of available buffers since the last call to this function.

Parameters:

address – The address of the endpoint to retrieve the buffer count for

Returns:

The number of available buffers

Public Static Functions

static std::unique_ptr<NetworkBackend> create(NetworkType type, const NetworkConfig &config, const std::shared_ptr<BaseEventLoop> &evloop)

Factory method to create a network backend object.

Creates a network backend object based on the network type and configuration. The event loop and config is passed as a parameter to the constructor of the network backend. The network type decides which network backend to create.

Parameters:

  • type – The type of the network backend

  • config – The network configuration

  • evloop – The event loop to use for network operations

Returns:

A unique pointer to the network backend object

Protected Attributes

NetworkConfig m_config
std::shared_ptr<BaseEventLoop> m_evloop