Client Stage (TCP)

This stage allows you to connect to a remote TCP server. All data that is read from this connection will be published into TcpPacketGroup messages.

While TCP connections are stream-oriented, and not packet-oriented, this stage treats each return from recv() as if it was a packet. These “packets” are grouped together.

Grouping is intended as a mechanism to batch messages on high-rate sensors, reducing performance overhead of publishing and logging individual TCP “packets”.

Configuration

Basic configuration is in the TcpClientStageConfig:

  • address - The address and port you expect to receive packets from.
  • reuse_address - If SO_REUSEADDR can be set on this socket.
  • group_size - The number of packets to bundle before publishing a group.
  • thread_priority - Priority to set the for the reading thread.
  • thread_processor_affinity - Which processors the reading thread can operate on.
  • enable_nodelay - If TCP_NODELAY should be on.
  • data_receive_timeout_ms - Reconnects if data hasn’t been received in this interval.
  • egress_buffer_size_b - The size of the local egress buffer.
  • kernel_receive_buffer_size_b - Size of the kernel receive buffer (zero for kernel default).
  • kernel_transmit_buffer_size_b - Size of the kernel transmit buffer (zero for kernel default).

The egress buffer size is used to determine how many bytes can be buffered in user-space (ie, in the stage itself), if the remote size isn’t keeping up. In general, you want this to be, at a minimum, the same size as the largest message you expect to send, but it should often be at least 2x that.

The kernel receive and transmit buffer sizes are used to configure the kernel-size of the buffers, allowing data to be buffered on the kernel rather than keeping it in userspace. This can help improve performance over slow links, and reduce the amount of time falling over into the egress buffer.

Interacting

This stage will start a background thread which services a socket. The thread will retry connecting the socket until it is successful. If the socket is ever disconnected, the stage will resume trying to reconnect.

All packet groups are published under packet_group in the stage’s namespace.

The stage listens for data to publish on the egress_packets channel. Anything received will be written over the TCP socket when connected (or dropped otherwise). You should set the configuration egress_buffer_size_b to at least the size of the largest message you expect to send; that controls the egress buffer and how much data the stage will queue if the other side isn’t reading fast enough.

Metrics

The stage periodically (at 1Hz) emits a SocketStats structure containing rate and size information. This is published under the socket_stats channel within the stage’s namespace.