1 \addtogroup book-self-building
3 \brief Provides information on how users can build order books
4 using atomic book updates from market data transmitted by CME
5 without using Handler's built-in facilities.
7 \section book-bricks Books Building Bricks
9 The Handler builds and maintains books for each security by
10 itself and exposes the results to user code if the user requests
11 order book maintenance through the Handler settings.
13 Sometimes there's a need to build and maintain books by own if,
14 for example, a custom book structure is used by the application.
15 Book atomic updates represent the same elementary quants of market
16 data as trades and statistics do.
18 To get notified on book atomic updates into a book it is necessary to
19 override OnixS::CME::MDH::SecurityListener::onBookAtomicUpdate members and
20 register listener instance via OnixS::CME::MDH::Handler::registerSecurityListener
23 \note Atomic updates may come at real time via incremental
24 feed or from snapshots while the market state is recovered.
25 Therefore, OnixS::CME::MDH::SecurityListener has two overloads
26 each of which exposes data based on its source.
28 An event exposes detailed information of elementary operations on bids or offers.
30 \note There's no ability to listen to atomic updates for the consolidated book
31 because this type of book is produced as a result of combining updated direct and
34 \section book-atomic-update-machinery Book Atomic Update Machinery and Relation with 'Book Update' Event
36 A book atomic update is delivered to client code via the
37 OnixS::CME::MDH::SecurityListener::onBookAtomicUpdate member
38 and represents an elementary operation over a book.
40 Therefore, the OnixS::CME::MDH::SecurityListener::onBookAtomicUpdate may be
41 invoked more frequently compare to the OnixS::CME::MDH::SecurityListener::onBookUpdate member.
42 In fact, the OnixS::CME::MDH::SecurityListener::onBookAtomicUpdate member usually is invoked
43 several times before a single invoke of the OnixS::CME::MDH::SecurityListener::onBookUpdate
46 When the Handler delivers an order book via the
47 OnixS::CME::MDH::SecurityListener::onBookUpdate callback,
48 that book is always in a valid and up-to-date state. In contrast, the
49 OnixS::CME::MDH::SecurityListener::onBookAtomicUpdate is a notification
50 on an elementary action over a book. Usually, there're multiple atomic
51 updates inside a single snapshot or incremental refresh transmitted by MDP.
52 As a result, a book may not be in a valid state between two atomic updates.
54 Only when the Handler processes all atomic updates belonging
55 to a single market event, a book becomes in a valid state. The
56 OnixS::CME::MDH::SecurityListener::onBookUpdate callbacks are
57 called exactly at the time when the Handler processes all atomic
58 updates and all book appear to be valid and up-to-date.
60 To build an order book properly, it is necessary also to listen to Hander events.
61 When error or data loss occurs, Handler may spawn market state recovery. Therefore,
62 if the Handler invokes the OnixS::CME::MDH::HandlerListener::onMarketRecovery, all
63 books for all securities in bounds of the channel must be empty. Afterwards, the
64 Handler will provide atomic updates recovered from snapshot messages.
