Introduction
This document provides a guidance to C++ programmers on using the B2BITS B3 UMDF SBE Handler. This document assumes the reader is familiar with Binary UMDF documentation found on the B3 web site.
Notes and tips are displayed in purple.
Source code fragments are displayed in code blocks. |
Complete API reference is available here.
Architecture Overview
In the architecture of the B3 UMDF SBE Handler, the major entities are Market Data Service, Channel, Resolver, and Instrument, having one-to-many relationships. Each entity is described in detail in subsequent sections. The number of instantiated objects of each entity depends on the type of client application and usage scenario.
using namespace B3::Umdf::Sbe; |
Market Data Service
Market Data Service object is a root object to access B3 Binary UMDF market data. The object maintains a collection of market data channels as well as resources shared across the channels. Market Data Service object is instantiated by specifying service unique name and options:
MarketDataServiceOptions marketDataServiceOptions;
marketDataServiceOptions.channelConfigFile = "b2b_b3_config.xml";
// ...
MarketDataService* marketDataService = createMarketDataService("MDS1", marketDataOptions);
|
Market Data Service object is initialized with the open method. Initialization involves loading SBE templates, channel configuration, and resource allocation:
marketDataServiceOptions->open(); |
Market Data service object can be finalized with the close method to free resources occupied:
marketDataServiceOptions->close(); |
Market Data Service object is destroyed with the destroy method:
marketDataServiceOptions->destroy(); |
The object reference is no longer valid.
Market Data Service Options
There are a number of options to control Market Data Service object behavior. Options are specified separately for incremental and recovery (instrument definition, snapshot) feeds. Options are equally applied to all channels of the Market Data Service object.
Tip: Use different Market Data Service objects to apply different options to groups of channels.
Market Data Service object is configured to use the only available type of instrument recovery on initial join and subsequent recoveries on gaps and sequence reset:
marketDataServiceOptions.joinRecoveryType = rtSnapshotRecovery; marketDataServiceOptions.gapRecoveryType = rtSnapshotRecovery; |
Market Data Service Sequence Options
Sequence options control sequence processing of the corresponding data feeds.
// Heartbeat interval (s). marketDataServiceOptions.incrementalSequenceOptions_.heartbeatInterval_ = 10; // Maximum gap allowed between last received and last processed packet. When reached, missing packets are considered completely lost. marketDataServiceOptions.incrementalSequenceOptions_.delayedPacketGap_ = 3; // Timeout (us) to wait for delayed packets before considering packets completely lost. marketDataServiceOptions.incrementalSequenceOptions_.delayedPacketTimeout_ = 10000; // Packet cache size (packets) to store received packets during recovery. marketDataServiceOptions.incrementalSequenceOptions_.packetCacheSize_ = 10000; |
Market Data Service Thread Options
Thread options control threads used to process packets of the corresponding data feeds. Market Data Service object can be configured to create a dedicated thread for each feed or use a limited pool of shared threads across all the corresponding feeds:
marketDataServiceOptions.incrementalThreadOptions_.threadPoolEnabled_ = true; marketDataServiceOptions.incrementalThreadOptions_.threadPoolSize_ = 4; |
Market Data Service object can be configured to spin threads and avoid idle state to reduce latency at the cost of CPU load and scalability:
marketDataServiceOptions.incrementalThreadOptions_.spinningEnabled_ = true; |
Market Data Service object can be configured to bind threads to a set of CPU cores to reduce latency at the cost of scalability:
marketDataServiceOptions.incrementalThreadOptions_.affinityMask_ = 0x3; |
Market Data Service Socket Options
Socket options control the socket layer used to receive packets of the corresponding data feeds. Market Data Service object can be configured to use a specific socket type:
marketDataServiceOptions.incrementalSocketOptions_.socketType_ = stMyricomDBL; |
Market Data Service object can be configured to use specific network interfaces for data feeds A and B on a multi-home host:
marketDataServiceOptions.incrementalSocketOptions_.interfaceAddressA_ = "172.17.94.7"; marketDataServiceOptions.incrementalSocketOptions_.interfaceAddressB_ = "172.17.94.8"; |
Market Data Service Logging Options
Logging options control logging behavior for testing and troubleshooting purpose. Market Data Service options can be configured to log all incoming and/or outcoming messages and events:
marketDataServiceOptions.loggingOptions_.logInMessages_ = true; marketDataServiceOptions.loggingOptions_.logOutMessages_ = true; |
Note: Logging degrades performance and is not intended for normal operation.
Channels
Channel object is used to receive market data of a particular B3 Binary UMDF channel and maintains a collection of resolvers and a collection of instruments. Channel objects for channels defined in the channel configuration file are instantiated automatically by the open method. Alternatively, Channel object can be instantiated explicitly by specifying channel unique id and options:
ChannelOptions channelOptions; channelOptions.snapshotAddressA_ = "233.205.192.106"; // ... Channel* channel = marketDataService->addChannel(80, channelOptions); |
Channel object can be retrieved by channel id:
Channel* channel = marketDataService->getChannel(80); |
Channel object can be removed to free resources occupied:
marketDataService->removeChannel(80); |
Resolvers
Resolver object is used to receive reference data (instrument definitions) of the channel. The client application may use one or more resolver objects to receive reference data. Resolver object is instantiated by specifying resolver unique id:
Resolver* resolver = channel->addResolver("BOVV");
|
Resolver object can be retrieved by resolver id:
Resolver* resolver = channel->getResolver("BOVV");
|
Resolver object can be removed to free resources occupied:
channel->removeResolver("BOVV");
|
The object reference is no longer valid.
Instruments
Instrument object is used to receive market data of a particular instrument. The client application may process a single instrument, a subset of instruments or all instruments of the channel. Market data messages of uninterested instruments are filtered out by the handler. Instrument object is instantiated by specifying instrument unique symbol, unique id and options:
InstrumentOptions instrumentOptions;
instrumentOptions.asset = "BOVV";
// ...
Instrument* instrument = channel->addInstrument("BOVV11", 300000012825, instrumentOptions, iboAll);
|
Instrument object can be retrieved by instrument symbol or instrument id:
Instrument* instrument = channel->getInstrument("BOVV11");
Instrument* instrument = channel->getInstrument(300000012825);
|
Instrument object can be removed to free resources occupied:
channel->removeInstrument("BOVV11");
channel->removeInstrument(300000012825);
|
Instrument Options
There are a number of options required by the handler to process instrument market data messages properly. Instrument asset and group options found in the instrument definition are required to process status update messages:
instrumentOptions.asset = "BOVV"; instrumentOptions.group = "9A"; |
Instrument Build Options
Instrument build options define what components of the instrument state are maintained by the handler.
iboLastTrade | iboExecutionStatistics | iboOrderBook; |
Tip: Specify build options of interest to reduce market data processing overhead.
Processing Reference Data
The client application implements the ResolverListener callback interface to process reference data events and messages:
class MyResolverListener : public ResolverListener
{
public:
virtual ResolverControlCode onEvent(Resolver* resolver, const ResolverEvent& event) override;
virtual ResolverControlCode onMessage(Resolver* resolver, const SecurityDefinitionMsg& message) override;
};
MyResolverListener myResolverListener;
|
Reference data processing is initiated by starting a Resolver object:
resolver->start(&myResolverListener, rsmAll); |
Once resolver is started, a complete instrument definition cycle is delivered to the resolver listener followed by any intraday instrument definition updates. Resolver listeners of different resolver objects receive reference data independently of each other. Reference data processing can be stopped with the stop method:
resolver->stop(); |
Resolver Subscription Mask
Resolver subscription mask defines what events are delivered to the resolver listener object:
rsmAll & ~rsmMessages; |
Tip: Specify events of interest to reduce reference data processing overhead.
Processing Reference Data Events
Reference data events are delivered to the client application via the onEvent callback function. It is expected the client application checks the type of a reference data event and processes it appropriately. Certain events have parameters associated with them. In the case the client application processes both reference and live data it can instantiate instrument objects of interest in the onEvent callback function:
ResolverControlCode MyResolverListener::onEvent(Resolver* resolver, const ResolverEvent& event)
{
if (event.type == reInstrumentAdded)
{
if (event.instrumentDefinition->asset == "BOVV")
{
resolver->getChannel()->addInstrument(event.instrumentDefinition);
}
}
// ...
}
|
The instrument symbol, id and options are deduced from the instrument definition object automatically.
Processing Reference Data Messages
Reference data messages (d) are delivered to the client application via the onMessage callback function. Reference data messages contain all the tags defined for the instrument. It is expected the client application checks the update action of the message and processes it appropriately.
Processing Live Data
The client application implements the InstrumentListener callback interface to process instrument live data events and messages:
class MyInstrumentListener : public InstrumentListener
{
public:
virtual InstrumentControlCode onEvent(Instrument* instrument, const InstrumentEvent& event) override;
virtual InstrumentControlCode onMessage(Instrument* instrument, const SnapshotOrdersMBOMsg& message) override;
virtual InstrumentControlCode onMessage(Instrument* instrument, const SnapshotHeaderMsg& message) override;
virtual InstrumentControlCode onMessage(Instrument* instrument, const SecurityStatusMsg& message) override;
virtual InstrumentControlCode onMessage(Instrument* instrument, const SecurityGroupPhaseMsg& message) override;
virtual InstrumentControlCode onMessage(Instrument* instrument, const EmptyBookMsg& message) override;
virtual InstrumentControlCode onMessage(Instrument* instrument, const ChannelResetMsg& message) override;
virtual InstrumentControlCode onMessage(Instrument* instrument, const OpeningPriceMsg& message) override;
virtual InstrumentControlCode onMessage(Instrument* instrument, const TheoreticalOpeningPriceMsg& message) override;
virtual InstrumentControlCode onMessage(Instrument* instrument, const ClosingPriceMsg& message) override;
virtual InstrumentControlCode onMessage(Instrument* instrument, const AuctionImbalanceMsg& message) override;
virtual InstrumentControlCode onMessage(Instrument* instrument, const QuantityBandMsg& message) override;
virtual InstrumentControlCode onMessage(Instrument* instrument, const PriceBandMsg& message) override;
virtual InstrumentControlCode onMessage(Instrument* instrument, const HighPriceMsg& message) override;
virtual InstrumentControlCode onMessage(Instrument* instrument, const LowPriceMsg& message) override;
virtual InstrumentControlCode onMessage(Instrument* instrument, const LastTradePriceMsg& message) override;
virtual InstrumentControlCode onMessage(Instrument* instrument, const SettlementPriceMsg& message) override;
virtual InstrumentControlCode onMessage(Instrument* instrument, const OpenInterestMsg& message) override;
virtual InstrumentControlCode onMessage(Instrument* instrument, const OrderMBOMsg& message) override;
virtual InstrumentControlCode onMessage(Instrument* instrument, const DeleteOrderMBOMsg& message) override;
virtual InstrumentControlCode onMessage(Instrument* instrument, const MassDeleteOrdersMBOMsg& message) override;
virtual InstrumentControlCode onMessage(Instrument* instrument, const TradeMsg& message) override;
virtual InstrumentControlCode onMessage(Instrument* instrument, const ForwardTradeMsg& message) override;
virtual InstrumentControlCode onMessage(Instrument* instrument, const ExecutionSummaryMsg& message) override;
virtual InstrumentControlCode onMessage(Instrument* instrument, const ExecutionStatisticsMsg& message) override;
virtual InstrumentControlCode onMessage(Instrument* instrument, const TradeBustMsg& message) override;
virtual InstrumentControlCode onMessage(Instrument* instrument, const NewsMsg& message) override;
};
MyInstrumentListener myInstrumentListener;
I
|
nstrument live data processing is initiated by subscribing an Instrument object:
instrument->subscribe(&myInstrumentListener, ismAll); |
Once the instrument is subscribed, the instrument data recovery is started followed by any incremental updates of the instrument live data. Instrument live data processing can be stopped with the unsubscribe method:
instrument->unsubscribe(); |
Instrument Subscription Mask
Instrument subscription mask defines what events are delivered to the instrument listener object:
ismUpdateEndEvents | ismMessages; |
Tip: Specify events of interest to reduce live data processing overhead.
Processing Live Data Events
Live data events are delivered to the client application via the onEvent callback function. It is expected the client application checks the type of a live data event and processes it appropriately. Some events have parameters associated with them while some events indicate an update of the corresponding component of the instrument state.
InstrumentControlCode MyInstrumentListener::onEvent(Instrument* instrument, const InstrumentEvent& event)
{
if (event.type == ieUpdateEnd)
{
auto indicator = event.updateEndFlags_.meIndicator();
if (indicator.test(MatchEventIndicator::EndOfEvent))
{
// process book update
const OrderBook* orderBook = instrument->getOrderBook();
// ...
}
}
}
|
Note: The client application may access the instrument state in the InstrumentListener callback interface functions only.
The client application should consider transaction (match event indicator) boundaries when processing live data updates. The ieUpdateEnd events indicate the end of updates of the certain type of data of a transaction, match event indicator is passed as a parameter to event handler.
Processing Market By Order (MBO) updates
MBO notifications are available as live data message updates delivered to the onMessage callback function. The client application may use live data messages to implement MBO data processing.
There are 6 callbacks related to MBO messages:
// MBO snapshot messages virtual InstrumentControlCode onMessage(Instrument* instrument, const SnapshotHeaderMsg& message); virtual InstrumentControlCode onMessage(Instrument* instrument, const SnapshotOrdersMBOMsg& message); // MBO incremental messages virtual InstrumentControlCode onMessage(Instrument* instrument, const EmptyBookMsg& message); virtual InstrumentControlCode onMessage(Instrument* instrument, const OrderMBOMsg& message); virtual InstrumentControlCode onMessage(Instrument* instrument, const DeleteOrderMBOMsg& message); virtual InstrumentControlCode onMessage(Instrument* instrument, const MassDeleteOrdersMBOMsg& message); |
Low Latency Configuration
To configure the handler for low latency at the cost of other criteria use these settings:
marketDataServiceOptions.recoveryThreadOptions.threadPoolEnabled = true; marketDataServiceOptions.recoveryThreadOptions.spinningEnabled = false; marketDataServiceOptions.recoveryThreadOptions.affinityMask = 0x0F; marketDataServiceOptions.recoverySocketOptions.socketType = stAsio; marketDataServiceOptions.incrementalThreadOptions.threadPoolEnabled = false; marketDataServiceOptions.incrementalThreadOptions.spinningEnabled = true; marketDataServiceOptions.incrementalThreadOptions.affinityMask = 0xF0; marketDataServiceOptions.incrementalSocketOptions.socketType = stSystem; marketDataServiceOptions.loggingOptions.logInMessages = false; marketDataServiceOptions.loggingOptions.logOutMessages = false; |
Client Samples
Two simple interactive console applications found in the samples folder demonstrate how to instantiate the handler, process reference and live data events and messages.
help (h) | Print commands |
open (o) channel_id | Open channel channel_id |
subscribe (s) channel_id 'symbol' | Subscribe to instrument symbol of channel channel_id |
subscribe (s) channel_id | Subscribe to all instruments of channel channel_id |
unsubscribe (u) channel_id 'symbol' | Unsubscribe from instrument symbol of channel channel_id |
unsubscribe (u) channel_id | Unsubscribe from all instruments of channel channel_id |
close (c) channel_id | Close channel channel_id |
close (c) | Close all channels |
exit (e) | Exit application |