1 \addtogroup event-listeners
3 \brief Explains concept of listeners and how Handler notifies
4 users on various aspects of market data processing and delivers
7 A primary purpose of the OnixS::CME::MDH::Handler class is to
8 process market data transmitted by MDP and to deliver the results
9 to the user for further analysis and processing.
11 The Handler processes market data asynchronously and uses a
12 concept of _events_ and _event listeners_ to notify a client
13 code about a particular occasion like reception of security
14 definition or direct book update.
16 \section events-listening Listening to Events
18 For a better experience the SDK groups events and provides C++ classes
19 with virtual members for each of those groups. Client code may override
20 any or all members of each listener to implement its reaction for a
21 particular event. For each listener the Handler exposes a special member
22 like OnixS::CME::MDH::Handler::registerSecurityListener which allows
23 associating an instance of the event listener with an appropriate group
24 of events in bounds of a particular instance of the OnixS::CME::MDH::Handler
27 Starting with this major release, the SDK does not use pure virtual
28 functions. Instead, each callback referring to a particular event has
29 an empty body thus providing default (empty) behavior. That lets users
30 override events they need thus making a code more clear and readable.
32 \note Associating listener for a particular event group with an instance of
33 the OnixS::CME::MDH::Handler class must be performed while the Handler is in
34 a stopped state. **Once the Handler is started, changing listener-event
35 associations is not allowed and leads to throwing an exception**.
37 Associating event listener with an instance of the OnixS::CME::MDH::Handler class
38 is also called _subscribing to an event_.
40 \section high-level-events Primary High-level Events
42 The table below describes primary groups of events exposed by the Handler
43 as well as depicts correspondence between the events, interfaces for listeners
44 and the OnixS::CME::MDH::Handler members to subscribe to an event group:
49 <th>Member to register listener</th>
53 <td>OnixS::CME::MDH::HandlerListener</td>
54 <td>OnixS::CME::MDH::Handler::registerListener</td>
56 Events triggered by the Handler during market data processing.
57 Events reflect different stages of processing session like entering
58 or leaving recovery cycle, recovery completion status and resuming
59 real-time data processing.
61 Previously, the Handler used a concept of state to inform subscribers
62 about similar events. However, new events allow the subscribers to handle
63 transitions better. For example, in case of recovery failure, previous
64 generations of the Handler signaled on the end of recovery with the
65 subsequent start of a new recovery loop.
67 However, at the end of recovery, there was no possibility to determine
68 whether recovery succeeded or restarted due to updates in a recovery
69 loop or failed at all. In the new events recovery status is exposed
70 via the new parameter of the OnixS::CME::MDH::RecoveryCompletionArgs
75 <td>OnixS::CME::MDH::MarketDataListener</td>
76 <td>OnixS::CME::MDH::Handler::registerMarketDataListener</td>
78 The Handler invokes members of the given listener when it
79 begins or ends processing of various market data entities
80 like a packet or a message.
82 An important aspect, related with the given listener, is
83 the fact that events are triggered only for market data
84 accepted by the Handler and according to the rules defined
85 by CME. THe Handler does not invoke members of the listener
86 for any duplicated or out-of-order packets.
88 The given listener provides additional flexibility for
89 the users while implementing their trading strategies
90 without requiring new groups of events.
92 \note The previous generations of the SDK exposed the
93 OnixS::CME::MDH::MessageProcessingListener listener with
94 a similar set of events. The OnixS::CME::MDH::MarketDataListener
95 represents an improved listener with additional events defining
96 packet processing bounds. Also, **in contrast to an older listener,
97 invocation of members belonging to the new listener is not affected
98 by filtering and is based solely on session processing parameters**.
102 <td>OnixS::CME::MDH::SecurityListener</td>
103 <td>OnixS::CME::MDH::Handler::registerSecurityListener</td>
105 Members of the given listener are invoked to reflect security-related
106 events like reception of trade, security status and order book update.
108 Each member exposed by the given listener provides read-only
109 access to security base attributes like its id, group, symbol
110 and a security-level sequence number allowing to track correctness
111 of processing market data referring to given security.
113 \note Previously, there was a bunch of listeners, each of which
114 was related to a particular market data entity like security
115 definition, trade, book update and security status. In the newest
116 releases, all those listeners have been merged into a single one
117 providing better clarify for the users. Also, a set of members has
118 been enhanced reflecting new events like handling unknown instruments,
119 a book reset for entire channel and detected gap on a security level.
121 By default, members of given listener are invoked for each
122 security available on a channel. However, it is possible to
123 restrict callback invocation for a set of securities using
124 OnixS::CME::MDH::Handler::selectInstruments member. See
125 \ref security-selection for more information.
129 <td>OnixS::CME::MDH::FeedListener</td>
130 <td>OnixS::CME::MDH::Handler::registerFeedListener</td>
132 The OnixS::CME::MDH::FeedListener members are invoked by the
133 Handler each time feed-related event occurs. Feeds are used by
134 the Handler while processing market data transmitted by CME MDP.
