Pages/ManipulatingBooks.md

Go to the documentation of this file.

\addtogroup book-handling

\brief Describes order book machinery. 

\section book-manipulations Order Books in the SDK

CME MDP maintains market by price (price-level) and market by order 
books. There are several types of books available for each security: 
**Market By Order (MBO)**, **Direct**, **Implied** and **Consolidated**. 
The SDK exposes the corresponding class for each of book type: 
OnixS::CME::MDH::MboBook, OnixS::CME::MDH::DirectBook, 
OnixS::CME::MDH::ImpliedBook and OnixS::CME::MDH::ConsolidatedBook. 
Each class exposes exact data available for a particular kind of 
the order book.


\note Although there are four different types of books, MDP
transmits data for only **MBO**, **direct** and **implied** types
of books. **Consolidated** books are being maintained by the Handler
locally using instances of **direct** and **implied** books
for a particular security.

The Handler notifies a client code through the 
OnixS::CME::MDH::SecurityListener::onBookUpdate callback
once a book of any type and for any security is updated. 

For market by price (MBP) books which **direct**, **implied** and **consolidated**
books are, the depth of book of a particular type is usually defined by security
definition and is exposed by the OnixS::CME::MDH::MbpBook::depth member. The returned 
value defines the maximum number of price levels which may exist in the book.

OnixS::CME::MDH::MbpBook::bids and OnixS::CME::MDH::MbpBook::asks
members of the OnixS::CME::MDH::MbpBook class can be used to access
price value and quantity information for all levels available in the book.

Similarly, interface of class gathering MBO book data includes
OnixS::CME::MDH::MboBook::bids and OnixS::CME::MDH::MboBook::asks
members to access details for all orders available in the book.

Also, order book maintenance is now explicitly defined by the Handler
configuration. 

The following code sample defines how to manage 
maintenance of order books using Handler settings:

~~~{.cpp}
HandlerSettings settings;

// Let Handler to maintain direct books. Once parameter is set 
// to 'true', Handler will invoke SecurityListener::onBookUpdate() 
// member passing instance of a valid direct book.
settings.bookManagement().directBooks().maintain(true);

// Given statement suppresses implied order book maintenance.
// However, if consolidated order book maintenance is enabled,
// implied order book will also be maintained. Therefore, given
// statement only suppresses order book update event triggering.
settings.bookManagement().impliedBooks().maintain(false);


// Let Handler to maintain consolidated books. Once parameter
// is set to 'true', Handler will invoke SecurityListener::onBookUpdate()
// member passing instance of a valid consolidated book.
settings.bookManagement().consolidatedBooks().maintain(true);
~~~

Depth of a MBP book of a particular type is usually defined by
security definition and is exposed by OnixS::CME::MDH::Book::depth
member. Returned value defines maximum number of price levels which
may exist in a particular book instance.

OnixS::CME::MDH::Book::bids and OnixS::CME::MDH::Book::offers
members of the OnixS::CME::MDH::Book class can be used to access
price value and quantity information for all levels available in
the book.

\section behavior-traits Behavioral Traits

The Handler constructs books for each security since the moment it receives
a 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 restriction exists because the Handler may change internal book structures 
at the same time. **If any data exposed by the OnixS::CME::MDH::Book class instance 
must be used outside of event handling, it must be copied before later use**. 

\see \ref book-construction-and-copying, OnixS::CME::MDH::SecurityListener