Class BackendAsyncmsg

• Defined in File BackendAsyncmsg.hpp

Nested Relationships

Nested Types

• Struct BackendAsyncmsg::EndpointHash

Inheritance Relationships

Base Type

• public netio3::NetworkBackend (Class NetworkBackend)

Class Documentation

class BackendAsyncmsg : public netio3::NetworkBackend

The TCP backend for the netio3 library.

The asyncmsg backend provides a network backend for the netio3 library using the TCP protocol. It makes use of the asyncmsg library for the underlying network communication.

Supports using both the boost asio event loop and the netio3 event loop. If the netio3 event loop is used, different options how the boost asio events are integrated are available:

• POLL: The boost asio events are polled in the netio3 event loop on a timer with a frequency defined by TIMER_INTERVAL. All events are polled. This might block the event loop indefinetly if processing an event takes as long as receiving new events.

• POLL_ONE: The boost asio events are polled in the netio3 event loop on a timer with a frequency defined by TIMER_INTERVAL. Only MAX_POLLS events are polled per timer event. This allows other callbacks to be invoked but limits the performance to TIMER_INTERVAL * MAX_POLLS events per second. If the TIMER_INTERVAL is very small it might add an overhead because boost asio is regularly polled for new events.

• STANDALONE: The boost asio events are processed in a separate thread. This is the most performant option as a separate event loop is used for boost asio. The netio3 event loop would be used for any other events (other backends, timers, signal, …). However, callbacks would need to be synchronized at a higher level.

• DELEGATE: The boost asio event loop is processing events received by the asyncmsg backend. However, it is not invoking callbacks directly but places events on a queue. If an event is added, a signal is fired that is registered on the netio3 event loop. The netio3 event loop will then process the event and call callbacks. This way, all callbacks are invoked synchronously, however, all messages are copied into a queue and an extra thread is running the boost asio event loop.

The asyncmsg backend is thread safe and does not offer an optinally thread unsafe mode. It is not intended for maximum performance anyways.

Public Functions

BackendAsyncmsg(const NetworkConfig &config, std::shared_ptr<BaseEventLoop> evloop)

Construct a new BackendAsyncmsg object.

In case STANDALONE or DELEGATE mode is used, start the event loop. In case polling is used start polling.

Parameters:

• config – The network configuration

• evloop – The event loop

~BackendAsyncmsg() override

Destroy the BackendAsyncmsg object.

Closes all open sessions and stops listening for any new connections. Stops the boost asio event loop in case it is used (STANDALONE or DELEGATE mode when the netio3 event loop is used as main event loop).

BackendAsyncmsg(const BackendAsyncmsg&) = delete

BackendAsyncmsg(BackendAsyncmsg&&) = delete

BackendAsyncmsg &operator=(const BackendAsyncmsg&) = delete

BackendAsyncmsg &operator=(BackendAsyncmsg&&) = delete

virtual void open_send_endpoint(const EndPointAddress &address, const ConnectionParameters &connection_params) override

Opens a new connection to send data to an endpoint.

Creates a Session and opens it to the specified endpoint.

Throws:

• InvalidEndpointAddress – If the address is invalid

• SendEndpointAlreadyExists – If a send connection to this endpoint was already requested

Parameters:

• address – The remote endpoint address

• connection_params – The connection parameters

virtual EndPointAddress open_listen_endpoint(const EndPointAddress &address, const ConnectionParametersRecv &connection_params) override

Register a server listening to new receive connections.

Create a Server to listen for incoming data on the specified address and port and accept all incoming connection requests on those. If port 0 was passed in, it figures out the port number that was used to open the connection and returns the actual address.

Throws:

• InvalidEndpointAddress – If the address is invalid

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

• FailedOpenListenEndpoint – If starting the server failed

Parameters:

• address – The address to listen on

• connection_params – The connection parameters (not relevant for TCP)

virtual void close_send_endpoint(const EndPointAddress &address) override

Close a send connection to a given endpoint.

Closes the connection to the specified endpoint.

Throws:

• InvalidEndpointAddress – If the address is invalid

• UnknownSendEndpoint – No connection was opened on this endpoint

Parameters:

address – The local endpoint address

virtual void close_listen_endpoint(const EndPointAddress &address) override

Stop listening for connections and close all receive connections on a given endpoint.

Stop listening for new connections on the specified endpoint and close all connections that were established to it. Stop and destroy the Server that was started on this endpoint.

Throws:

• InvalidEndpointAddress – If the address is invalid

• UnknownListenEndpoint – No server was started on this endpoint

• FailedCloseListenEndpoint – Stopping the serve failed

Parameters:

address – The remote endpoint address

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) override

Sends data to the specified endpoint.

This function sends the specified data over the TCP connection to the specified endpoint. A connection must be registered for this endpoint before sending data. The session for the provided connection is asked to asynchronously send the data. Therefore, this call is not blocking. Since the send operation is asynchronous, this function always returns OK (or throws). The data are not copied and therefore need to be remain valid until the on_send_complete callback is invoked.

A copy of the header data is stored and is prepended to the message. The key will be provided on the on_send_completed callback to the user.

Throws:

• InvalidEndpointAddress – If the address is invalid

• UnknownSendEndpoint – No connection was opened on this endpoint

Parameters:

• address – The remote endpoint address

• data – The pointer to the data to be sent

• 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(const EndPointAddress &address, std::span<const iovec> iov, std::span<const std::uint8_t> header_data, std::uint64_t key) override

Sends data stored in an iovec to the specified endpoint.

This function sends the data specified in a vector of iovec structures over the TCP connection to the specified endpoint. A connection must be registered for this endpoint before sending data. The session for the provided connection is asked to asynchronously send the data. The data are not copied and therefore need to be remain valid until the send operation is completed. This is signified by the on_send_complete callback.

A copy of the header data is stored and is prepended to the message. The key will be provided on the on_send_completed callback to the user.

Throws:

• InvalidEndpointAddress – If the address is invalid

• UnknownSendEndpoint – No connection was opened on this endpoint

Parameters:

• address – The remote endpoint address

• iov – The vector of iovec structures representing the data to be sent

• 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 std::uint8_t> data, std::span<const std::uint8_t> header_data, std::uint64_t key) override

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.

Throws:

• NotSupported – if the operation is not supported by the backend

• InvalidEndpointAddress – If the address is invalid

• UnknownSendEndpoint – No connection was opened on this endpoint

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) override

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.

Throws:

• NotSupported – if the operation is not supported by the backend

• InvalidEndpointAddress – If the address is invalid

• UnknownSendEndpoint – No connection was opened on this endpoint

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) override

Retrieves a network buffer for sending data.

Buffers are managed by send connection. This function returns a buffer for the provided connection if available. If no buffer is available, nullptr is returned.

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

Throws:

• InvalidEndpointAddress – If the address is invalid

• UnknownSendEndpoint – No connection was opened on this endpoint

Parameters:

address – The remote endpoint address

Returns:

A pointer to the network buffer (or nullptr if none available)

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

Sends a network buffer to the specified endpoint.

This function sends the data buffer over the TCP connection to the specified endpoint. A connection must be registered for this endpoint before sending data. The session for the provided connection is asked to asynchronously send the buffer. 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.

Throws:

• InvalidEndpointAddress – If the address is invalid

• UnknownSendEndpoint – No connection was opened on this endpoint

Parameters:

• address – The remote endpoint address

• buffer – The network buffer to be sent

Returns:

The status of the send operation

virtual std::size_t get_num_available_buffers(const EndPointAddress &address) override

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

Only works for endpoints that are opened for buffered sending. Zero-copy endpoints return 0. Returns the mininum number of available buffers since the last call to this function.

Throws:

UnknownSendEndpoint – if the send endpoint does not exist

Parameters:

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

Returns:

The number of available buffers