itch::Parser Class Reference

A high-performance parser for the NASDAQ TotalView-ITCH 5.0 protocol. More...

#include <parser.hpp>

Public Member Functions
	Parser ()=default
	Constructs a Parser instance.
auto	parse (const char *data, size_t size, const MessageCallback &callback) -> void
	Parses messages from a memory buffer and invokes a callback for each.
auto	parse (const char *data, size_t size) -> std::vector< Message >
	Parses all messages from a memory buffer and returns them in a vector.
auto	parse (const char *data, size_t size, const std::vector< char > &messages) -> std::vector< Message >
	Parses messages from a buffer, returning only those of specified types.
auto	parse (std::istream &data, const MessageCallback &callback) -> void
	[Convenience Wrapper] Parses messages from a stream via a callback.
auto	parse (std::istream &data) -> std::vector< Message >
	[Convenience Wrapper] Parses all messages from a stream into a vector.
auto	parse (std::istream &data, const std::vector< char > &messages) -> std::vector< Message >
	[Convenience Wrapper] Parses and filters messages from a stream.
auto	parse (std::span< const std::byte > data, const MessageCallback &callback) -> void
	Parses messages from a byte span and invokes a callback for each.
auto	parse (std::span< const std::byte > data) -> std::vector< Message >
	Parses all messages from a byte span and returns them in a vector.
auto	parse (std::span< const std::byte > data, const std::vector< char > &messages) -> std::vector< Message >
	Parses messages from a byte span, keeping only the requested types.
auto	set_error_callback (ErrorCallback callback) -> void
	Registers a callback invoked for each recoverable framing problem.
auto	unknown_message_count () const noexcept -> std::uint64_t
	The number of frames skipped because their type byte was unknown.
auto	malformed_message_count () const noexcept -> std::uint64_t
	The number of frames skipped because their declared length was too small for the message type.
auto	reset_diagnostics () noexcept -> void
	Resets the accumulating diagnostics counters to zero.

Detailed Description

A high-performance parser for the NASDAQ TotalView-ITCH 5.0 protocol.

This class is designed to parse a raw binary feed of ITCH 5.0 messages, handle message framing (based on the 2-byte length prefix), and deserialize the byte payloads into structured, type-safe C++ objects.

The primary interface is designed for maximum performance, operating directly on a pre-loaded, contiguous block of memory (a const char* buffer). This approach avoids all per-message memory allocations and stream I/O overhead, allowing for throughput measured in gigabytes per second.

For convenience, the parser also provides std::istream based wrappers. These are easier to use for simple cases but are significantly slower, as they must read the entire stream into an in-memory buffer before parsing.

Note

This parser assumes the input is a raw, sequenced ITCH 5.0 feed without any higher-level protocol framing (e.g., SoupBinTCP packet headers).

Definition at line 78 of file parser.hpp.

Constructor & Destructor Documentation

Parser()

itch::Parser::Parser ( )

default

Constructs a Parser instance.

Dispatch is driven by a compile-time table keyed on the message type byte, so no per-instance setup is required.

Member Function Documentation

parse() [1/9]

auto itch::Parser::parse	(	const char *	data,
		size_t	size,
		const MessageCallback &	callback
	)		-> void

Parses messages from a memory buffer and invokes a callback for each.

This is the core, high-performance parsing method. It iterates through the provided memory buffer, identifies each message, and invokes the callback with the parsed object. This approach is highly efficient as it performs no memory allocations in its main loop.

Parameters

data	A pointer to the start of the memory buffer containing ITCH data.
size	The total size of the buffer in bytes.
callback	A function to be called for each successfully parsed message.

Exceptions

std::runtime_error

if the buffer ends unexpectedly in the middle of a message.

Definition at line 343 of file parser.cpp.

Referenced by itch::ReplayEngine::replay().

parse() [2/9]

auto itch::Parser::parse	(	const char *	data,
		size_t	size
	)		-> std::vector<Message>

Parses all messages from a memory buffer and returns them in a vector.

A convenience method that parses the entire buffer and collects all messages into a single vector.

Parameters

data	A pointer to the start of the memory buffer.
size	The total size of the buffer in bytes.

Returns

A std::vector<Message> containing all parsed messages.

Exceptions

std::runtime_error

on buffer parsing errors.

Note

Be cautious with very large buffers, as this will load all parsed messages into memory, consuming significant RAM.

Definition at line 351 of file parser.cpp.

References itch::average_message_size.

parse() [3/9]

auto itch::Parser::parse	(	const char *	data,
		size_t	size,
		const std::vector< char > &	messages
	)		-> std::vector<Message>

Parses messages from a buffer, returning only those of specified types.

A convenience method that parses the entire buffer but only collects messages whose type character is present in the messages filter list.

Parameters

data	A pointer to the start of the memory buffer.
size	The total size of the buffer in bytes.
messages	A vector of message type characters to keep (e.g., {'A', 'P'}).

Returns

A std::vector<Message> containing only the filtered messages.

Exceptions

std::runtime_error

on buffer parsing errors.

Definition at line 358 of file parser.cpp.

References itch::average_message_size, and message_type.

parse() [4/9]

auto itch::Parser::parse	(	std::istream &	data,
		const MessageCallback &	callback
	)		-> void

[Convenience Wrapper] Parses messages from a stream via a callback.

This method reads the entire stream into an internal memory buffer and then calls the high-performance buffer-based parser. It is provided for ease of use with stream-based APIs.

Parameters

data	A reference to an std::istream opened in binary mode.
callback	A function to be called for each successfully parsed message.

Exceptions

std::runtime_error

on stream reading errors.

Note

For maximum performance, load the data into memory yourself and use the const char* overload directly.

Definition at line 443 of file parser.cpp.

References itch::read_stream_into_buffer().

parse() [5/9]

auto itch::Parser::parse

(

std::istream &

data

)

-> std::vector<Message>

[Convenience Wrapper] Parses all messages from a stream into a vector.

This method reads the entire stream into memory before parsing.

Parameters

data	A reference to an std::istream opened in binary mode.

Returns

A std::vector<Message> containing all parsed messages.

Exceptions

std::runtime_error

on stream reading errors.

Note

Be cautious with large files, as this will load the entire raw file and all parsed messages into memory.

Definition at line 448 of file parser.cpp.

References itch::read_stream_into_buffer().

parse() [6/9]

auto itch::Parser::parse	(	std::istream &	data,
		const std::vector< char > &	messages
	)		-> std::vector<Message>

[Convenience Wrapper] Parses and filters messages from a stream.

This method reads the entire stream into memory before parsing and filtering.

Parameters

data	A reference to an std::istream opened in binary mode.
messages	A vector of message type characters to keep (e.g., {'A', 'E', 'P'}).

Returns

A std::vector<Message> containing only the filtered messages.

Exceptions

std::runtime_error

on stream reading errors.

Definition at line 453 of file parser.cpp.

References itch::read_stream_into_buffer().

parse() [7/9]

auto itch::Parser::parse	(	std::span< const std::byte >	data,
		const MessageCallback &	callback
	)		-> void

Parses messages from a byte span and invokes a callback for each.

The std::span overloads are the preferred modern interface: the span carries its own size, which prevents the pointer/length desynchronization that the raw (const char*, size_t) overloads are prone to. Those raw overloads are retained as thin shims for C interop.

Parameters

data	A view over the contiguous buffer containing ITCH data.
callback	A function to be called for each successfully parsed message.

Exceptions

std::runtime_error

if the buffer ends in the middle of a message.

Definition at line 389 of file parser.cpp.

parse() [8/9]

auto itch::Parser::parse

(

std::span< const std::byte >

data

)

-> std::vector<Message>

Parses all messages from a byte span and returns them in a vector.

Parameters

data	A view over the contiguous buffer containing ITCH data.

Returns

A std::vector<Message> containing all parsed messages.

Exceptions

std::runtime_error

if the buffer ends in the middle of a message.

Definition at line 393 of file parser.cpp.

parse() [9/9]

auto itch::Parser::parse	(	std::span< const std::byte >	data,
		const std::vector< char > &	messages
	)		-> std::vector<Message>

Parses messages from a byte span, keeping only the requested types.

Parameters

data	A view over the contiguous buffer containing ITCH data.
messages	A vector of message type characters to keep (e.g., {'A', 'P'}).

Returns

A std::vector<Message> containing only the filtered messages.

Exceptions

std::runtime_error

if the buffer ends in the middle of a message.

Definition at line 397 of file parser.cpp.

set_error_callback()

auto itch::Parser::set_error_callback

(

ErrorCallback

callback

)

-> void

Registers a callback invoked for each recoverable framing problem.

Passing an empty function clears any previously installed callback. The default behavior, with no callback installed, is to silently skip and count the offending frame.

Parameters

callback

The diagnostics callback to install, or an empty function to clear any previously installed callback.

Definition at line 424 of file parser.cpp.

unknown_message_count()

auto itch::Parser::unknown_message_count ( ) const -> std::uint64_t

inlinenoexcept

The number of frames skipped because their type byte was unknown.

Returns

The running count of frames skipped for an unrecognized type byte.

Definition at line 241 of file parser.hpp.

malformed_message_count()

auto itch::Parser::malformed_message_count ( ) const -> std::uint64_t

inlinenoexcept

The number of frames skipped because their declared length was too small for the message type.

Returns

The running count of frames skipped for a declared length too small for their message type.

Definition at line 250 of file parser.hpp.

reset_diagnostics()

auto itch::Parser::reset_diagnostics ( ) -> void

inlinenoexcept

Resets the accumulating diagnostics counters to zero.

Definition at line 255 of file parser.hpp.

---

The documentation for this class was generated from the following files:

• parser.hpp
• parser.cpp