Introduction

Felix-client is a library providing a thread safe user interface to interact with felix-star applications. Felix-client-thread is built around felix-client providing two additional features:

  1. It automatically manages the event-loop thread of the underlying network library (hence the name felix-client-thread).

  2. It decouples the user application from the felix release. The user application is built against felix-interface and can be run against any felix release since the API is always extended in a backwards compatible way. The user application can be run against a different felix release by simply redefining LD_LIBRARY_PATH.

Functionality

The felix-client-thread API provides functions to:

  • subscribe to (e-)links published by felix-tohost

  • send messages to felix-toflx

  • talk to felix-register

  • control trickle configuration

  • register arbitrary user-defined events to be executed by the event loop

The next sections describe the API in more detail.

Compilation

The headers and libraries are founds in each FELIX release. You can compile against them using CMake like this:

1set(FELIX_RELEASE /path/to/felix/release/<BINARY_TAG>)
2
3add_executable(felix-client-app main.cpp)
4
5target_include_directories(felix-client-app PRIVATE ${FELIX_RELEASE}/include)
6target_link_directories(felix-client-app PRIVATE ${FELIX_RELEASE}/lib)
7target_link_libraries(felix-client-app PRIVATE felix-client-thread)

You can also use find_package:

1set(Felix_ROOT "/path/to/felix/release/<BINARY_TAG>")
2
3find_package(Felix REQUIRED COMPONENTS felix-client-thread)
4
5add_executable(felix-client-app main.cpp)
6target_link_libraries(felix-client-app PRIVATE felix::felix-client-thread)

Running the application

To run the application, you need to set the LD_LIBRARY_PATH environment variable to point to the directory containing the FELIX libraries. You can do this by sourcing the setup script provided by the FELIX release:

source /path/to/felix/release/<BINARY_TAG>/setup.sh

Alternatively, for a minimal setup, you can set the LD_LIBRARY_PATH environment variable directly and setup the environment variables for RDMA:

export LD_LIBRARY_PATH=/path/to/felix/release/<BINARY_TAG>/lib:/path/to/felix/release/<BINARY_TAG>/lib64:$LD_LIBRARY_PATH
export FI_VERBS_TX_IOV_LIMIT=30
export FI_VERBS_RX_IOV_LIMIT=30
export FI_VERBS_TX_SIZE=1024
export FI_VERBS_RX_SIZE=1024
export RDMAV_FORK_SAFE=1

Event loop

The event loop is a thread that runs in the background and handles network events. I handles all asynchronous events such as incoming messages, connection and disconnection events or user-defined events. The event loop is started automatically when the felix-client-thread instance is created and stopped when the instance is destroyed.

Hint

One felix-client-thread instance always spawns one event loop thread. All events are handled in this thread. The user application can create multiple instances of felix-client-thread, each with its own event loop thread if a single thread is not sufficient.

Callbacks

Callbacks are user-defined functions that are called by the event loop when an event occurs. The user can define callbacks for incoming messages, connection and disconnection events or user-defined events.

Important

Callbacks are executed by the event loop thread. Blocking on a callback prevents any other network event to be reported. This can slow down the event loop and, potentially, impact the sender through back-pressure. Make sure to avoid blocking calls in callbacks.

Attention

Callbacks will be called in the context of the event loop thread. Make sure callbacks accessing resources used by the user thread are accessed in a thread-safe way.

Deprecation notice

Large parts of the pre-5.2 API are deprecated. It is still supported but it is recommended to migrate to the new API as soon as you do not need to maintain backwards compatibility with older releases. The last section provides a migration guide to the new API. The deprecated API will be removed in a future release.