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.

...

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.

...

Image Added

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:

...

 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.

...

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_.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_.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:

...

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:

...

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:

...

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:

...

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.

...

Processing Reference Data

The client application implements the ResolverListener callback interface to process reference data events and messages:

...

resolver->stop();

Resolver Subscription Mask

Resolver subscription mask defines what events are delivered to the resolver listener object:

...

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:

...

 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:

...

 instrument->unsubscribe();

Instrument Subscription Mask

Instrument subscription mask defines what events are delivered to the instrument listener object:

...

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.

...

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.

...