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 dxfcpp::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 dxfcpp::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 dxfcpp::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) noexcept=0
	Changes unique per-symbol index of this event.

Additional Inherited Members
Static Public Attributes inherited from dxfcpp::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()

virtual std::int64_t dxfcpp::TimeSeriesEvent::getEventId ( ) const

inlinevirtualnoexcept

Returns unique per-symbol index of this event.

Returns: unique per-symbol index of this event.

Deprecated: Use getIndex()

◆ getIndex()

std::int64_t dxfcpp::TimeSeriesEvent::getIndex ( ) const

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.