Represents time-series snapshots of some process that is evolving in time or actual events in some external system that have an associated time stamp and can be uniquely identified. More...
#include <TimeSeriesEvent.hpp>
Inheritance diagram for TimeSeriesEvent:
Public Types | |
| using | Ptr = std::shared_ptr<TimeSeriesEvent> |
| The alias to a type of shared pointer to the TimeSeriesEvent object. | |
| Public Types inherited from IndexedEvent | |
| using | Ptr = std::shared_ptr<IndexedEvent> |
| The alias to a type of shared pointer to the IndexedEvent object. | |
Public Member Functions | |
| const IndexedEventSource & | getSource () const &noexcept override |
| Returns the source identifier for this event, which is always DEFAULT for time-series events. | |
| std::int64_t | getIndex () const noexcept override |
| Returns unique per-symbol index of this event. | |
| virtual std::int64_t | getEventId () const noexcept |
| Returns unique per-symbol index of this event. | |
| virtual std::int64_t | getTime () const noexcept=0 |
| Returns timestamp of the event. | |
| Public Member Functions inherited from IndexedEvent | |
| virtual std::int32_t | getEventFlags () const noexcept=0 |
| Returns transactional event flags. | |
| virtual EventFlagsMask | getEventFlagsMask () const noexcept=0 |
| Returns transactional event flags. | |
| virtual void | setEventFlags (std::int32_t eventFlags) noexcept=0 |
| Changes transactional event flags. | |
| virtual void | setEventFlags (const EventFlagsMask &eventFlags) noexcept=0 |
| Changes transactional event flags. | |
| virtual void | setIndex (std::int64_t index)=0 |
| Changes unique per-symbol index of this event. | |
Additional Inherited Members | |
| Static Public Attributes inherited from IndexedEvent | |
| static const EventFlag | TX_PENDING = EventFlag::TX_PENDING |
0x01 - A bitmask to get transaction pending indicator from the value of eventFlags property. | |
| static const EventFlag | REMOVE_EVENT = EventFlag::REMOVE_EVENT |
0x02 - A bitmask to get removal indicator from the value of eventFlags property. | |
| static const EventFlag | SNAPSHOT_BEGIN = EventFlag::SNAPSHOT_BEGIN |
0x04 - A bitmask to get snapshot begin indicator from the value of eventFlags property. | |
| static const EventFlag | SNAPSHOT_END = EventFlag::SNAPSHOT_END |
0x08 - A bitmask to get snapshot end indicator from the value of eventFlags property. | |
| static const EventFlag | SNAPSHOT_SNIP = EventFlag::SNAPSHOT_SNIP |
0x10 - A bitmask to get snapshot snip indicator from the value of eventFlags property. | |
| static const EventFlag | SNAPSHOT_MODE = EventFlag::SNAPSHOT_MODE |
0x40 - A bitmask to set snapshot mode indicator into the value of eventFlags property. | |
Detailed Description
Represents time-series snapshots of some process that is evolving in time or actual events in some external system that have an associated time stamp and can be uniquely identified.
For example, TimeAndSale events represent the actual sales that happen on a market exchange at specific time moments, while Candle events represent snapshots of aggregate information about trading over a specific time period.
Time-series events can be used with DXFeedTimeSeriesSubscription to receive a time-series history of past events. Time-series events are conflated based on unique index for each symbol. Last indexed event for each symbol and index is always delivered to event listeners on subscription, but intermediate (next-to-last) events for each symbol+index pair are not queued anywhere, they are simply discarded as stale events.
Timestamp of an event is available via time property with a millisecond precision. Some events may happen multiple times per millisecond. In this case they have the same time, but different index. An ordering of index is the same as an ordering of time. That is, an collection of time-series events that is ordered by index is ascending order will be also ordered by time in ascending order.
Time-series events are a more specific subtype of IndexedEvent. All general documentation and Event Flags section, in particular, applies to time-series events. However, the time-series events never come from multiple sources for the same symbol and their source is always DEFAULT.
Unlike a general IndexedEvent that is subscribed to via DXFeedSubscription} using a plain symbol to receive all events for all indices, time-series events are typically subscribed to using TimeSeriesSubscriptionSymbol class to specific time range of the subscription. There is a dedicated DXFeedTimeSeriesSubscription class that is designed to simplify the task of subscribing for time-series events.
TimeSeriesEventModel class handles all the snapshot and transaction logic and conveniently represents a list of current time-series events ordered by their time. It relies on the code of AbstractIndexedEventModel to handle this logic. Use the source code of AbstractIndexedEventModel for clarification on transactions and snapshot logic.
Classes that implement this interface may also implement LastingEvent interface, which makes it possible to use DXFeed::getLastEvent() method to retrieve the last event for the corresponding symbol.
Publishing time-series
When publishing time-series event with DXPublisher::publishEvents() method on incoming TimeSeriesSubscriptionSymbol the snapshot of currently known events for the requested time range has to be published first.
A snapshot is published in the descending order of index (which is the same as the descending order of time), starting with an event with the largest index and marking it with TimeSeriesEvent::SNAPSHOT_BEGIN bit in eventFlags. All other event follow with default, zero eventFlags. If there is no actual event at the time that was specified in subscription fromTime property, then event with the corresponding time has to be created anyway and published. To distinguish it from the actual event, it has to be marked with TimeSeriesEvent::REMOVE_EVENT bit in eventFlags. TimeSeriesEvent::SNAPSHOT_END bit in this event's eventFlags s optional during publishing. It will be properly set on receiving end anyway. Note, that publishing any event with time that is below subscription fromTime also works as a legal indicator for the end of the snapshot.
Both TimeAndSale and Candle time-series events define a sequence property that is mixed into an index property. It provides a way to distinguish different events at the same time. For a snapshot end event the sequence has to be left at its default zero value. It means, that if there is an actual event to be published at subscription fromTime with non-zero sequence, then generation of an additional snapshot end event with the subscription fromTime and zero sequence is still required.
Member Function Documentation
◆ getEventId()
|
inlinevirtualnoexcept |
Returns unique per-symbol index of this event.
- Returns
- unique per-symbol index of this event.
References getIndex().
◆ getIndex()
|
inlineoverridevirtualnoexcept |
Returns unique per-symbol index of this event.
Event indices are unique within event symbol. Typically event index for a time series event includes time inside.
Implementation notes
The most common scheme for event indices is to set highest 32 bits of event index to event timestamp in seconds. The lowest 32 bits are then split as follows. Bits 22 to 31 encode milliseconds of time stamp, and bits 0 to 21 encode some kind of a sequence number.
Ultimately, the scheme for event indices is specific for each even type. The actual classes for specific event types perform the corresponding encoding.
- Returns
- unique per-symbol index of this event.
Implements IndexedEvent.
Reimplemented in Underlying.
Referenced by getEventId().
◆ getSource()
|
inlineoverridevirtualnoexcept |
Returns the source identifier for this event, which is always DEFAULT for time-series events.
- Returns
- The source identifier for this event, which is always DEFAULT for time-series events.
Implements IndexedEvent.
Reimplemented in Underlying.
References IndexedEventSource::DEFAULT.
◆ getTime()
|
pure virtualnoexcept |
Returns timestamp of the event.
The timestamp is in milliseconds from midnight, January 1, 1970 UTC.
- Returns
- timestamp of the event.
Implemented in Candle, Greeks, TheoPrice, TimeAndSale, and Underlying.
