OnixS ICE iMpact Multicast Price Feed Handler C++ library  8.18.0
API documentation
Manipulating Order Books
Advanced Programming

Market book in the Handler

Once a subscription is started Handler builds and synchronizes books for each market for which product definition was previously received.

Book abstraction is exposed by the OnixS::ICE::iMpact::MarketData::OrderBook class.

There were several types of books currently supported by the Handler:

The Handler is capable to build and maintain books of any type for the subscribed markets.

Handler passes instances of OnixS::ICE::iMpact::MarketData::OrderBook class to the listeners of book changes registered through the Handler's OnixS::ICE::iMpact::MarketData::Handler::registerOrderBookChangeListener member.

OnixS::ICE::iMpact::MarketData::OrderBook class exposes two major members to access market orders and price-levels:

Accessing Product Definitions

See Product Definitions topic for more information concerning how to store product definitions. Use OnixS::ICE::iMpact::MarketData::OrderBook::marketId to access corresponding product definition.

Market book behavioral traits

An important aspect of book behavior is that not all its members available for all types of books. In particular, OnixS::ICE::iMpact::MarketData::OrderBook::bidOrders (OnixS::ICE::iMpact::MarketData::OrderBook::offerOrders) members works only for full order depth books. Therefore, it will return an empty array in case of price-level book. For this reason, when accessing members of OnixS::ICE::iMpact::MarketData::OrderBook instance it's necessary to check its type using OnixS::ICE::iMpact::MarketData::OrderBook::depth member.

Also, since books are changed in time, do not store references to obtained orders and price levels. Any instance exposed by book through OnixS::ICE::iMpact::MarketData::OrderBook::bidOrders (OnixS::ICE::iMpact::MarketData::OrderBook::offerOrders) or OnixS::ICE::iMpact::MarketData::OrderBook::bids and OnixS::ICE::iMpact::MarketData::OrderBook::offers members is valid only in bounds of handling routine being called by the Handler to process changes in book. It may be deleted right after handling accomplished as a response to a new message from received from Multicast Price Feed. Therefore, instances can only be used to access the information they store.

See Event Listeners topic for more information concerning how to get notified about changes in the market books.

Example

The following sample demonstrates how book attributes can be processed by the appropriate listener:

virtual void onBookUpdated(const OrderBook& book, const MessageInfo& msgInfo)
{
ProductDefinitionsConstEntry foundDefinition = productDefinitions_.find(book.marketId());
if (productDefinitions_.end() != foundDefinition)
{
const ProductDefinition& definition = foundDefinition->second;
std::cout
<< "Changes detected in "
<< BookDepth::toString (book.depth())
<< " book for market "
<< marketId
<< ": "
<< std::endl;
if (book.offers().empty())
{
std::cout << "No offers available yet. ";
}
else
{
std::cout
<< "Price of the first offer is "
<< book.offers().at(0).price
<< ". ";
}
if (book.bids().empty())
{
std::cout << "No bids available yet. ";
}
else
{
std::cout
<< "Price of the first bid is "
<< book.bids().at(0).price
<< ". ";
}
std::cout << std::endl;
}
}

Behavioral Traits

The Handler constructs books for each security since the moment it receives definition for that security. Books are changed in time and their members are not thread-safe. The Handler uses own synchronization strategies while updating the books. Therefore, do not access price levels information outside of book-related event handling as well as do not store references to any book instance and data returned by its members like asks and bids collections. This is because Handler may change internal book structures at the same time. If any data exposed by the OnixS::ICE::iMpact::MarketData::OrderBook class instance must be used outside of event handling, it must be copied before later use.

Storage order

Container Sorting Order Prices Example
OnixS::ICE::iMpact::MarketData::OrderBook::bids Descending by price 5, 4, 3, 2, 1
OnixS::ICE::iMpact::MarketData::OrderBook::offers Ascending by price 1, 2, 3, 4, 5
OnixS::ICE::iMpact::MarketData::OrderBook::bidOrders Order of arrival 1, 5, 2, 4, 3
OnixS::ICE::iMpact::MarketData::OrderBook::offerOrders Order of arrival 1, 5, 2, 4, 3

Implied Prices

The Handler supports both implied and non-implied feeds. For more details about implied prices please see ICE Futures Implied Prices.

Order Book Events

The Handler provides the following order book related events:

Order Book Reset Event

When the Handler just started or when it needs to recover the current market state for snapshot it can trigger this event. For users, it is an indication that the previous order book state is no longer valid and should be dropped. This event is usually used to update some local user's books if it holds copies.

Order Book Changed Event

In each datagram, we have one or several messages which can cause changes in the order book. After processing each of such messages the Handler triggers this event. For example, if for the same market the Handler receives two messages in a single datagram like "Delete Price Level" and "Add Price Level" it will trigger two OnixS::ICE::iMpact::MarketData::OrderBookChangeListener::onOrderBookChanged events.

Order Book Updated Event

If for OnixS::ICE::iMpact::MarketData::OrderBookChangeListener::onOrderBookChanged the Handler triggers that event for all the messages in the datagram, OnixS::ICE::iMpact::MarketData::OrderBookUpdateListener::onOrderBookUpdated is triggered after processing all the messages for the same market in the current datagram. Like in the previous example, if we have "Delete Price Level" and "Add Price Level" message in the same datagram for the same market the Handler will trigger OnixS::ICE::iMpact::MarketData::OrderBookUpdateListener::onOrderBookUpdated only once after processing of both the messages.

Order Book Bundle Updated Event

ICE has a concept of the bundle where some long sequence of messages can be in two or more datagrams. In this case, ICE sends special messages called OnixS::ICE::iMpact::MarketData::BundleMarker. If OnixS::ICE::iMpact::MarketData::OrderBookBundleUpdateListener is registered, the Handler will analyze these bundle markers and trigger this event for all the affected market only when it receives OnixS::ICE::iMpact::MarketData::BundleMarker with OnixS::ICE::iMpact::MarketData::BundleMarker::isTransactionEnd field set to true.

Disable Order Book Processing

The Handler will enable order book building logic only if you subscribe to one of following listeners:

If you don't register any of these listeners, the internal order books building logic will be completely disabled and the Handler will only parse the messages.

Complexity of Order Book Update Operations

We implemented the order book building logic on top of the most efficient data structures to make handling of order book updates as fast as possible. Let's take a closer look at the different types of order books and the complexity of the order book update operations.

Price Level Books

Message Complexity
AddPriceLevel Linear in the distance between the position of the new price level and end of the container
ChangePriceLevel Constant
DeletePriceLevel Linear in the number of elements after the price level deleted (moving)

Full Order Depth Books

Parameter Complexity
AddModifyOrder Constant (store an order) plus linear (add/update price level)
DeleteOrder Constant (remove order) plus linear (remove price level)
Trade Constant (update/remove order) plus linear (update price level)