Constructing a felix-client-thread instance
===========================================

The constructor of the felix-client-thread class takes its
:cpp:struct:`configuration struct<FelixClientThreadExtension520::ConfigV2>` as a single argument.

.. doxygenstruct:: FelixClientThreadExtension520::ConfigV2
  :no-link:
  :outline:
  :members:
  :undoc-members:

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 :ref:`subscription<Subscribing to felix-tohost>` and
:ref:`sending data<Sending data to felix-toflx>` provide more details about the callbacks and their usage.

.. doxygentypedef:: FelixClientThreadExtension520::OnDataCallbackV2
  :no-link:
  :outline:

:cpp:type:`This callback<FelixClientThreadExtension520::OnDataCallbackV2>` 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.


.. doxygentypedef:: FelixClientThreadExtension520::OnBufferCallback
  :no-link:
  :outline:

:cpp:type:`This callback<FelixClientThreadExtension520::OnBufferCallback>` 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.


.. doxygentypedef:: FelixClientThreadInterface::OnInitCallback
  :no-link:


.. doxygentypedef:: FelixClientThreadInterface::OnConnectCallback
  :no-link:
  :outline:

:cpp:type:`This callback<FelixClientThreadInterface::OnConnectCallback>` 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.


.. doxygentypedef:: FelixClientThreadInterface::OnDisconnectCallback
  :no-link:
  :outline:

:cpp:type:`This callback<FelixClientThreadInterface::OnDisconnectCallback>` 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.


.. doxygentypedef:: FelixClientThreadExtension520::OnConnectionRefusedCallback
  :no-link:
  :outline:

:cpp:type:`This callback<FelixClientThreadExtension520::OnConnectionRefusedCallback>` 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.


.. doxygentypedef:: FelixClientThreadExtension520::OnSubscriptionsLostCallback
  :no-link:
  :outline:

:cpp:type:`This callback<FelixClientThreadExtension520::OnSubscriptionsLostCallback>` 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.


.. doxygentypedef:: FelixClientThreadExtension520::OnResubscriptionCallback
  :no-link:
  :outline:

:cpp:type:`This callback<FelixClientThreadExtension520::OnResubscriptionCallback>` 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 :cpp:type:`Properties map<FelixClientThreadInterface::Properties>`.

.. doxygentypedef:: FelixClientThreadInterface::Properties
  :no-link:

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

.. doxygengroup:: PROPERTIES
  :no-link:

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

.. code-block:: cpp
  :linenos:

  #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);
  }