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, netio3::libfabric::BackendLibfabricConnectionless

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_active_endpoint(const EndPointAddress &address, const ConnectionParameters &connection_params) = 0

Opens an active endpoint for the specified address with the given connection parameters.

The active endpoint will connect to a listener on the specified address and port. Its capabilities are defined by the connection parameters.

Parameters:

  • address – The address of the endpoint to open (remote address)

  • connection_params – The connection parameters for the endpoint

Throws:

  • InvalidEndpointAddress – if the endpoint address is invalid

  • FailedOpenActiveEndpoint – if the active endpoint could not be opened

  • ActiveEndpointAlreadyExists – if the active endpoint already exists

  • InvalidConnectionParameters – if the connection parameters conflict with global settings (shared buffers)

virtual EndPointAddress open_listen_endpoint(const EndPointAddress &address, const ConnectionParameters &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 active endpoint. 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 (local address)

  • connection_params – The connection parameters for spawned endpoints

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

  • InvalidConnectionParameters – if the connection parameters conflict with global settings (shared buffers)

Returns:

The actual address the server is listening on

virtual void close_active_endpoint(const EndPointAddress &address) = 0

Closes the active endpoint for the specified address.

Can be used to close both active endpoints directly opened by calling open_active_endpoint and endpoints that were spawned by a listen endpoint.

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

  • UnknownActiveEndpoint – if the endpoint does not exist

  • FailedCloseActiveEndpoint – if closing the active endpoint failed

virtual void close_listen_endpoint(const EndPointAddress &address) = 0

Closes the listen endpoint for the specified address.

Shall also close all active endpoints that were spawned by this listen endpoint.

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 endpoint 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

  • UnknownActiveEndpoint – if the endpoint does not exist or has no send capabilities

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

  • UnknownActiveEndpoint – if the endpoint does not exist or has no send capabilities

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:

  • UnknownActiveEndpoint – if the endpoint does not exist or has no send capabilities

  • 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:

UnknownActiveEndpoint – if the endpoint does not exist or has no send capabilities

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