Farfler™ Network

Getting Started   |   Subscribing   |   Publishing   |   Multiple Instances   |   Author

Farfler Network is a C++ library that implements a distributed publish-subscribe system using UDP for discovery and TCP for reliable communication. It allows nodes to discover each other, establish connections, and exchange messages on various topics.

Getting Started

To begin using Farfler Network, you need to set up the basic network infrastructure. This involves creating an IO context, initializing the network with a node name, and running the IO context in a separate thread. Here's how to set up the basic environment:

#include <boost/asio.hpp>
#include <farfler/network/network.hpp>
#include <thread>

int main() {
  boost::asio::io_context io_context;
  Network(io_context, "node");
  std::thread t([&io_context]() { io_context.run(); });

  ...

  io_context.stop();
  t.join();
  return 0;
}

Subscribing

Farfler Network offers flexible subscription options. You can subscribe to receive messages from all nodes with Subscribe, only from remote nodes with SubscribeOnline, or only from the local node with SubscribeOffline. This allows for fine-grained control over message reception. Here are examples of all three subscription types:

Network::Subscribe("temperature", [](const double &message) {
  std::cout << "Received temperature from any node: " << message << std::endl;
});

Network::SubscribeOnline("status", [](const bool &message) {
  std::cout << "Received online status from remote node: " << message << std::endl;
});

Network::SubscribeOffline("position", [](const Vector3 &message) {
  std::cout << "Received local position: (" << message.x << ", " << message.y << ", " << message.z << ")" << std::endl;
});

Publishing

Similarly, you can publish messages to all subscribed nodes with Publish, specifically to remote nodes with PublishOnline, or only to the local node with PublishOffline.

Network::Publish("temperature", 22.5);

Network::PublishOnline("status", true);

Network::PublishOffline("position", Vector3(1.0, 2.0, 3.0));

Multiple Network Instances

The library supports the creation and management of multiple independent network instances within a single application. This feature is particularly useful for scenarios where you need to isolate different parts of your network communication or manage distinct network configurations. Here's how you can work with multiple network instances:

// Create multiple network instances
Network network1(io_context, "network1");
Network network2(io_context, "network2");

// Publish to specific networks
Network::Publish(network1, "temperature", 22.5);
Network::Publish(network2, "humidity", 45.0);

// Subscribe to topics on specific networks
Network::Subscribe(network1, "temperature", [](const double &temp) {
  std::cout << "Network1 temperature: " << temp << " °C" << std::endl;
});

Network::Subscribe(network2, "humidity", [](const double &humidity) {
  std::cout << "Network2 humidity: " << humidity << "%" << std::endl;
});

Singleton Instance Fallback

Farfler Network implements a convenient singleton instance fallback mechanism. This feature allows you to use network operations without explicitly specifying a network instance, defaulting to the first created network instance. Here's how it works:

// Create multiple network instances
Network network1(io_context, "network1");
Network network2(io_context, "network2");

// The first created network (network1) becomes the default singleton instance

// These operations will use network1 by default
Network::Publish("temperature", 22.5);
Network::Subscribe("humidity", [](const double &humidity) {
  std::cout << "Humidity: " << humidity << "%" << std::endl;
});

// You can still explicitly specify a network when needed
Network::Publish(network2, "pressure", 1013.25);

This mechanism allows you to write cleaner code when working with a single network or when one network is predominantly used, while still maintaining the ability to manage multiple networks when necessary.

Made with ❤️ by Daniel Bacsur