Constructing a felix-client-thread instance

The constructor of the felix-client-thread class takes its configuration struct as a single argument.

struct ConfigV2

Public Members

OnDataCallbackV2 on_data_callback = {nullptr}

OnBufferCallback on_buffer_callback = {nullptr}

OnInitCallback on_init_callback = {nullptr}

OnConnectCallback on_connect_callback = {nullptr}

OnDisconnectCallback on_disconnect_callback = {nullptr}

OnConnectionRefusedCallback on_refused_callback = {nullptr}

OnSubscriptionsLostCallback on_subscriptions_lost_callback = {nullptr}

OnResubscriptionCallback on_resubscription_callback = {nullptr}

Properties property = {}

The config structure has two parts: The callbacks and the properties.

Note

The name is chosen to maintain backwards compatibility with the previous version of the API.

Callbacks

This section provides a short overview of the callbacks that can be defined in the config structure. The following sections about subscription and sending data provide more details about the callbacks and their usage.

typedef std::function<void(uint64_t fid, std::span<const uint8_t> data, uint8_t status)> FelixClientThreadExtension520::OnDataCallbackV2

This callback is called whenever a message is received from the felix-tohost.

Caution

The message pointer reported by OnDataCallback will become invalid as the function returns. The reason is that, once read, network buffers are returned and reused to receive new messages.

typedef std::function<void(std::span<const uint8_t> data)> FelixClientThreadExtension520::OnBufferCallback

This callback is called whenever a network buffer is received from the felix-tohost. The entire buffer is passed to the callback. Unlike the on data callback, messages in the network buffers are interleaved by headers. The users must unpack the messages parsing the headers.

Caution

The message pointer reported by OnBufferCallback will become invalid as the function returns. The reason is that, once read, network buffers are returned and reused to receive new messages.

typedef std::function<void()> FelixClientThreadInterface::OnInitCallback

Callback executed by event loop thread at start.

typedef std::function<void(uint64_t fid)> FelixClientThreadInterface::OnConnectCallback

This callback is called whenever a subscription to felix-tohost or a connection to felix-toflx is established in an asynchronous way. If the connection is established synchronously, the callback is not called.

typedef std::function<void(uint64_t fid)> FelixClientThreadInterface::OnDisconnectCallback

This callback is called whenever the user unsubscribed from felix-tohost in an asynchronous way.

Note

The user has no control on closing the connection to felix-toflx.

typedef std::function<void(uint64_t fid)> FelixClientThreadExtension520::OnConnectionRefusedCallback

This callback is called whenever the user attempted to open a connection to felix-toflx in an asynchronous way and this connection was refused by the server.

typedef std::function<void(const std::set<std::uint64_t> &fids)> FelixClientThreadExtension520::OnSubscriptionsLostCallback

This callback is called whenever a subscription to felix-tohost has been lost (i.e. the connection was closed without an unsubscription request). This can happen if the connection to felix-tohost is lost because the server is down or the network is down.

typedef std::function<void(std::uint64_t fid)> FelixClientThreadExtension520::OnResubscriptionCallback

This callback is called whenever a previously lost subscription to felix-tohost has been automatically re-established.

Properties

To initialise the communication with FELIX a set of parameters needs to be defined. The configuration parameters are contained in the Properties map.

typedef std::map<std::string, std::string> FelixClientThreadInterface::Properties

Data structure to hold configuration parameters defined in felix_client_properties header.

The parameters are listed below. As described, only some need to be initialised, others are optionals or for expert use

group PROPERTIES

Defines

FELIX_CLIENT_LOCAL_IP_OR_INTERFACE

Local IP or interface.

FELIX_CLIENT_LOG_LEVEL

Log-level (trace, debug, info, warning, error, fatal)

Deprecated:

Set using ers environment variable instead.

FELIX_CLIENT_BUS_DIR

Path to felix-bus directory, to be accessible by both local and remote endpoint.

FELIX_CLIENT_BUS_GROUP_NAME

Optional: felix-bus group name, default: FELIX.

FELIX_CLIENT_IO_BUS_GROUP_NAME

Optional: felix-bus io group name, default: FELIX_IO.

FELIX_CLIENT_VERBOSE_BUS

Optional: set to “True” to enable verbose logging in felix-bus.

FELIX_CLIENT_TIMEOUT

Optional: subscription timeout in ms.

Deprecated:

Pass timeout to subscribe function instead.

FELIX_CLIENT_NETIO_PAGES

Optional, expert: override number of netio pages.

Deprecated:

Taken from bus instead.

FELIX_CLIENT_NETIO_PAGESIZE

Optional, expert: override size of netio pages.

Deprecated:

Taken from bus instead.

FELIX_CLIENT_THREAD_AFFINITY

Optional: set thread affinity.

FELIX_CLIENT_READ_ENV

Optional, expert: enable retrieval of configuration variables from environment.

FELIX_CLIENT_USE_ASIO_EVLOOP

Optional, Use ASIO event loop. Preferrable for TCP traffic.

FELIX_CLIENT_USE_THREAD_UNSAFE_NETIO

Optional, expert: Use thread unsafe mode for netio.

FELIX_CLIENT_THREAD_NAME

Optional, expert: Name of the felix-client event loop thread.

Tip

Boolean values should be set to True (case sensitive) if they are to be used.

Note

If FELIX_CLIENT_READ_ENV is set to True (case sensitive), all settings are read from environment varibles. The names of the environment variables are the same as the property names. If the settings is provided in addition, it overrides the environment variable.

Configuration of network connections

The parameters for the network connections opened to communicate to felix-star are defined in the bus file written by felix-star. If you want to change the type of the network connection (TCP or RDMA) or whether to use buffered or unbuffered sending, you need to modify the command line arguments of felix-star applications (tohost and toflx).

Example

#include <print>

#include <felix/felix_client_thread.h>

void on_init() {
  std::println("Client thread initialized");
}

int main()
{
  // Create the configuration struct
  FelixClientThread::ConfigV2 config;

  config.on_init_callback = on_init;
  // Other callbacks ...

  config.properties[FELIX_CLIENT_LOCAL_IP_OR_INTERFACE] = "127.0.0.1";
  config.properties[FELIX_CLIENT_BUS_DIR] = "/tmp/bus";
  config.properties[FELIX_CLIENT_BUS_GROUP_NAME] = "FELIX";
  config.properties[FELIX_CLIENT_VERBOSE_BUS] = "False";
  config.properties[FELIX_CLIENT_USE_ASIO_EVLOOP] = "False";

  // Create the client thread
  FelixClientThread client(config);
}