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.

Open

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:

Market Data Service object is initialized with the open method. Initialization involves loading SBE templates, channel configuration, and resource allocation:

 Market Data service object can be finalized with the close method to free resources occupied:

 Market Data Service object is destroyed with the destroy method:

 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.

 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:

Market Data Service Sequence Options

Sequence options control sequence processing of the corresponding data feeds. 

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:

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:

 Market Data Service object can be configured to bind threads to a set of CPU cores to reduce latency at the cost of scalability:

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:

 Market Data Service object can be configured to use specific network interfaces for data feeds A and B on a multi-home host:

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:

Channel object can be retrieved by channel id:

 Channel object can be removed to free resources occupied:

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 object can be retrieved by resolver id:

Resolver object can be removed to free resources occupied:

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:

Instrument object can be retrieved by instrument symbol or instrument id:                                                                                                                                          

Instrument object can be removed to free resources occupied:

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:

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:

 Reference data processing is initiated by starting a Resolver object:

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

nstrument live data processing is initiated by subscribing an Instrument object:

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

Low Latency Configuration

To configure the handler for low latency at the cost of other criteria use these settings:

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.