Skip to content

UDP Multicast

Status: Planned

This module is not yet implemented. The design below represents the target architecture.

Overview

UDP multicast group management for one-to-many and many-to-many real-time data distribution. Common in market data feeds, telemetry systems, and distributed sensor networks. Uses IGMP for group membership and the kernel's multicast routing for efficient delivery.

Multicast Architecture

┌──────────────────────────────────────────────────────────────────┐
│                      Multicast Group 239.1.1.1                    │
│                                                                    │
│  ┌──────────┐     ┌───────────────┐     ┌──────────┐            │
│  │ Publisher │────►│   Network     │────►│Subscriber│            │
│  │ (source)  │     │  (L2 switch/  │     │   (A)    │            │
│  └──────────┘     │   router)     │     └──────────┘            │
│                    │               │     ┌──────────┐            │
│                    │  IGMP group   │────►│Subscriber│            │
│                    │  membership   │     │   (B)    │            │
│                    └───────────────┘     └──────────┘            │
│                                          ┌──────────┐            │
│                                     ────►│Subscriber│            │
│                                          │   (C)    │            │
│                                          └──────────┘            │
└──────────────────────────────────────────────────────────────────┘

Planned API

typedef struct {
    int       fd;                /* UDP socket */
    uint32_t  group_addr;        /* Multicast group (network byte order) */
    uint16_t  port;              /* UDP port */
    int       if_index;          /* Interface for multicast */
    uint8_t   ttl;               /* Time-to-live (hop count) */
    bool      loopback;          /* Receive own transmissions */
    bool      joined;            /* Currently a member */
} mcast_socket_t;

/* Lifecycle */
int mcast_create(mcast_socket_t *ms, const char *group_ip, uint16_t port,
                 const char *if_name);
int mcast_join(mcast_socket_t *ms);      /* IGMP join */
int mcast_leave(mcast_socket_t *ms);     /* IGMP leave */
void mcast_close(mcast_socket_t *ms);

/* Send/Receive */
ssize_t mcast_send(mcast_socket_t *ms, const void *data, size_t len);
ssize_t mcast_recv(mcast_socket_t *ms, void *buf, size_t len,
                   struct sockaddr_in *src, int timeout_ms);

/* Configuration */
int mcast_set_ttl(mcast_socket_t *ms, uint8_t ttl);
int mcast_set_loopback(mcast_socket_t *ms, bool enable);
int mcast_set_source_filter(mcast_socket_t *ms, uint32_t source_ip); /* SSM */

Multicast Address Ranges

Range Scope Use
224.0.0.0/24 Link-local IGMP, OSPF (TTL=1, not forwarded)
224.0.1.0/24 Internetwork NTP, other well-known
239.0.0.0/8 Organization-local Private multicast (recommended)
232.0.0.0/8 Source-specific (SSM) Single-source multicast

Performance Targets

Metric Target Notes
Publish latency < 5 µs Application to wire
Receive latency < 5 µs Wire to application
IGMP join time < 10 ms Group membership setup
Packet loss 0% (LAN) No congestion control

Implementation Roadmap

  • Socket creation with SO_REUSEADDR + SO_REUSEPORT
  • IGMP group join/leave (IP_ADD_MEMBERSHIP, IP_DROP_MEMBERSHIP)
  • Multicast TTL and loopback configuration
  • Source-specific multicast (SSM) filtering
  • Integration with epoll_reactor (EPOLLIN on mcast fd)
  • Sequence number tracking for gap detection
  • Multicast-to-unicast recovery protocol
  • Benchmark: latency distribution, jitter measurement