As a C++ class library, the Handler uses exceptions to report errors that occur while performing an action. For example, the Handler raises a regular exception to report the inability to connect to the Multicast Price Feed server or a failure in the login procedure. However, once a subscription to market data succeeds, the Handler cannot report any further errors because it performs all handling asynchronously in the background. For this reason, the Handler exposes the ErrorListener interface and Handler::registerErrorListener member so you can subscribe to and handle errors.
Once an instance of ErrorListener is assigned to the Handler, it invokes the ErrorListener::onError member each time an error occurs. ErrorListener::onError has two input parameters that define the error code (identifier) and a human-readable description of the error.
The KnownErrors type contains constants and descriptions for errors that may occur while processing market data from Multicast Price Feed.
An important aspect of the Handler's behavior is that, in the usual case, there is nothing specific you must do about errors. Once a market data subscription starts successfully, the Handler processes incoming data and handles failures on its own without further action. You do not need to restart the subscription manually. The Handler performs error recovery optimally. For example, for network-related problems, it rebuilds only the books and market states that depend on the problematic Multicast Price Feed channel. It does not invalidate and rebuild the entire subscription.
See the Event Listeners topic for more information on how to subscribe to a particular event.
The Handler is able to recover the market state for all the product definitions from requested market subscriptions in case some packets are lost. All the logic is implemented according to 5.2. Synchronization with Live Updates of the official ICE iMpact Multicast Feed Technical Specification.
In general, users don't need to do anything to handle missing packets, as the Handler will start the recovery procedure and reconstruct the books automatically. The recovery follows this sequence:
If you want to tune the snapshot recovery process, use the SnapshotRecoveryOptions structure. It controls how long the Handler waits for snapshots (snapshotRecoveryTimeoutInMilliseconds), how many recovery attempts it makes (maximumNumberOfSnapshotRecoveryAttempts), and the sizes of the packet queues used during recovery (maximumSizeOfLiveMessageQueue and maximumSizeOfSnapshotMessageQueue). See the API reference for the exact accepted values and defaults of each member.
The two queue-size settings are the ones relevant to PacketQueueOverflow. While recovery is in progress the Handler buffers packets in these queues, and when more arrive than the configured limit allows, the oldest are discarded and the warning is raised. For sizing guidance on these limits, see Warning Handling.
To reduce the risk of unnecessary delay caused by unavailable Historical Replay, consider lowering sequenceGapMargin and gapTimeoutInMilliseconds so that the Handler detects gaps early and reaches snapshot recovery sooner. Note that entering snapshot recovery is also what activates the packet queues (the inline Historical Replay path does not), so detecting gaps more aggressively makes recovery windows more frequent; if you tune these down, keep an eye on PacketQueueOverflow and size the queues accordingly. See also the lost multicast packets troubleshooting guide for advice on reducing UDP packet loss at the network level.
A sequence number is an unsigned 32-bit value, so a busy channel eventually reaches its largest value, 4,294,967,295. The exchange announces that with a Sequence ID Rollover Message, published as the last message of the block that reaches the maximum. The next packet on that channel arrives with the session number incremented by one and the sequence number restarted at 1. The exchange rolls the corresponding snapshot channel over at the same time; the Handler needs nothing from it, because a snapshot feed is stopped and reset between recoveries and adopts whatever session arrives next.
No market data is lost at a rollover, so the Handler does not treat it as a new session: the order books are kept, no snapshot recovery is requested and no packet gap is reported. Subscribe to ExchangeListener::onSequenceIdRollover to be notified when one happens. The event is informational, and the MessageInfo it carries describes the block the message arrived in - so MessageInfo::sessionNumber reports the session that is ending, not the one that follows.
The Handler falls back to its ordinary session number change handling - reporting FeedListener::onSessionNumberChange and restarting - whenever the transition does not match the announcement exactly:
The Handler does not implement automatic failover between network interface cards (NICs). If the NIC used for multicast reception stops working, the Handler will not switch to a second NIC automatically.
The Handler supports simultaneous reception on multiple NICs. Set HandlerSettings::networkInterface to a comma-delimited list of interface names (Linux) or IP addresses (Windows). The Handler joins each multicast group on all listed interfaces, so packets arriving on any of them are received on the same socket at the same time. Duplicate packets carrying the same sequence numbers from multiple NICs are discarded transparently by the existing sequence deduplication logic. The one exception is empty message blocks with HandlerSettings::notifyOnEmptyMulticastMessageBlocks enabled: the Handler reports each copy that reaches it rather than deduplicating them. See Empty Multicast Message Blocks.
This provides packet-level redundancy: a packet missed on one NIC may still be received on another, reducing the chance of a sequence gap.
