Broadcast C++ Toolkit
|
FEConsumer is a class which serves as the primary interface for interacting with the broadcast server. More...
#include <FEConsumer.h>
Public Types | |
enum | SnapshotMode { NO_SNAPSHOT, REQUIRE_SNAPSHOT } |
Set of possible snapshot modes when subscribing. More... | |
enum | DataMode { LIVE, DELAYED, CANNED } |
Set of possible data modes when subscribing. More... | |
typedef int | SocketType |
Operating system file descriptor type. | |
typedef MD::MD_Message | MsgType |
Market data message type. | |
typedef void(* | MessageCallback )(const std::string &topic, MsgType &msg, void *closure) |
Callback signature for receiving market data messages. More... | |
typedef void(* | EventCallback )(const Event &e, void *closure) |
Callback signature for receiving events. More... | |
typedef void(* | LoggingCallback )(const LogMessage *messages, size_t count) |
Callback signature for receiving logging messages. More... | |
Public Member Functions | |
bool | connected () const |
Connected state of the FEConsumer. More... | |
bool | authenticated () const |
Authenticated state of the FEConsumer. More... | |
bool | logged_in () const |
Login state of the FEConsumer. More... | |
bool | is_subscribed (const std::string &topic) const |
Checks for a subscription to a topic. More... | |
unsigned int | timeout_sec () const |
Gets the seconds to spend on a single command before returning a timeout error. More... | |
unsigned int | snapshot_timeout_sec () const |
Gets the seconds to wait to receive all snapshot messages before returning a timeout error. More... | |
unsigned int | heartbeat_timeout_sec () const |
Gets the seconds to wait to receive a response after sending a heartbeat before considering the connection as timed out. More... | |
unsigned int | heartbeat_interval_sec () const |
Gets the seconds to wait to receive all snapshot messages before returning a timeout error. More... | |
unsigned int | max_snapshot_queue_size () const |
Gets the maximum number of messages to hold for each topic while waiting for snapshots. More... | |
void | event_cb (EventCallback callback) |
Sets the EventCallback() used for receiving events. More... | |
void | event_cb (EventCallback callback, void *closure) |
Sets the EventCallback() used for receiving events. More... | |
void | timeout_sec (unsigned int seconds) |
Sets the seconds to spend on a single command before returning a timeout error. More... | |
void | snapshot_timeout_sec (unsigned int seconds) |
Sets the seconds to wait to receive all snapshot messages before returning a timeout error. More... | |
void | heartbeat_timeout_sec (unsigned int seconds) |
Sets the seconds to wait to receive a response after sending a heartbeat before considering the connection as timed out. More... | |
void | heartbeat_interval_sec (unsigned int seconds) |
Sets the seconds to wait between sending heartbeats. More... | |
void | max_snapshot_queue_size (unsigned int size) |
Sets the maximum number of messages to hold for each topic while waiting for snapshots. More... | |
void | enable_latency_tracking (unsigned int bucket_interval_sec) |
Enables tracking message latency throughout the consumer. More... | |
void | disable_latency_tracking () |
Disables tracking message latency throughout the consumer. More... | |
Error | register_callback (const std::string &topic_prefix, FEConsumer::MessageCallback callback, void *closure, SocketType &fd_out) |
Registers a callback for messages with topics starting with the given prefix. More... | |
Error | unregister_callback (const std::string &topic_prefix) |
Unregisters a callback previously registered with register_callback(). More... | |
Error | unregister_callback (SocketType fd) |
Unregisters a callback previously registered with register_callback(). More... | |
Error | get_notify_socket (const std::string &topic_prefix, SocketType &fd_out) |
Returns the file descriptor for a given topic prefix. More... | |
Error | dispatch (long timeout_ms) |
Convenience function for dispatching on all registered callbacks. More... | |
Error | dispatch_fd (SocketType fd) |
Dispatches messages for the callback with the given file descriptor. More... | |
void | set_notify_queue_message_limit (size_t limit) |
Sets the notify queue message limit. More... | |
size_t | get_notify_queue_message_limit () |
Gets the notify queue message limit. More... | |
void | set_notify_queue_time_limit_ms (int limit) |
Sets the notify queue time limit in milliseconds. More... | |
int | get_notify_queue_time_limit_ms () |
Gets the notify queue time limit. More... | |
FEConsumer (int sub_count, int worker_count, int high_watermark) | |
Constructor. More... | |
FEConsumer (int sub_count, int worker_count) | |
Synchronous methods | |
A synchronous method will block until it completes. All synchronous methods will return an Error if something went wrong or Error::NoError otherwise. If the operation does not complete within timeout_sec() seconds, a timeout Error will be returned. Synchronous methods cannot be called from FEConsumer callbacks. | |
Error | stop () |
Does nothing. More... | |
Error | authenticate (const std::string &host, const std::string &user, const std::string &serial, const std::string &key_id, const std::string &key, const std::string &counter, const std::string &path, bool force_input) |
Authenticates with the given credentials. More... | |
Error | authenticate (const std::string &host, const std::string &user, const std::string &key_id, const std::string &key, const std::string &counter, const std::string &path, bool force_input) |
Authenticates with the given credentials. More... | |
Error | connect () |
Connects to the broadcast server. More... | |
Error | disconnect () |
Disconnects from the broadcast server. More... | |
Error | log_in (bool request_files=true) |
Logs in to the broadcast server. More... | |
Error | subscribe (const std::string &topic, SnapshotMode snapshot_mode, DataMode data_mode) |
Subscribes to a topic. More... | |
Error | unsubscribe (const std::string &topic) |
Unsubscribes from a topic. More... | |
Error | request_file (const std::string &filename, std::string &contents_out) |
Requests a configuration file with a given name. More... | |
Asynchronous methods | |
An asynchronous method will return immediately and will send an Event via the event_cb() when it completes. If the operation does not complete within timeout_sec() seconds, an Event containing a timeout Error will be generated. Asynchronous methods can be called from FEConsumer callbacks. | |
void | stop_async () |
Does nothing. More... | |
void | authenticate_async (const std::string &host, const std::string &user, const std::string &serial, const std::string &key_id, const std::string &key, const std::string &counter, const std::string &path, bool force_input) |
void | authenticate_async (const std::string &host, const std::string &user, const std::string &key_id, const std::string &key, const std::string &counter, const std::string &path, bool force_input) |
void | connect_async () |
Connects to the broadcast server. More... | |
void | disconnect_async () |
Disconnects from the broadcast server. More... | |
void | log_in_async (bool request_files=true) |
Logs in to the broadcast server. More... | |
void | subscribe_async (const std::string &topic, SnapshotMode snapshot_mode, DataMode data_mode) |
void | unsubscribe_async (const std::string &topic) |
Unsubscribes from a topic. More... | |
void | request_file_async (const std::string &filename) |
Requests a configuration file with a given name. More... | |
Static Public Member Functions | |
static Error | log_open (const std::string &filename, bool append) |
Opens a file with the given filename to log messages from the toolkit. More... | |
static void | log_close () |
Closes the log file previously opened with log_open(). | |
static void | enable_verbose_logging () |
Turn on logging additional messages. | |
static void | disable_verbose_logging () |
Turn off logging additional messages. | |
static void | set_logging_callback (LoggingCallback callback) |
Sends logging messages to function instead of file/console. More... | |
Static Public Attributes | |
static const int | NO_TIMEOUT = 0 |
Value which indicates commands should never time out. | |
static const int | HWM_UNLIMITED = 0 |
Value which indicates no messages should ever be dropped due to reaching the high watermark. | |
FEConsumer is a class which serves as the primary interface for interacting with the broadcast server.
typedef void(* FactSet::Datafeed::FEConsumer::EventCallback)(const Event &e, void *closure) |
Callback signature for receiving events.
e | The event being received. |
closure | The closure that was given when the callback was set or NULL if no closure was given. |
typedef void(* FactSet::Datafeed::FEConsumer::LoggingCallback)(const LogMessage *messages, size_t count) |
Callback signature for receiving logging messages.
For use with FEConsumer::set_logging_callback() in order to integrate with existing logging frameworks.
messages | Array of logging messages returned |
count | Length of messages array |
typedef void(* FactSet::Datafeed::FEConsumer::MessageCallback)(const std::string &topic, MsgType &msg, void *closure) |
Callback signature for receiving market data messages.
topic | The topic of msg. |
msg | The message being received. |
closure | The closure that was given when the callback was set or NULL if no closure was given. |
FactSet::Datafeed::FEConsumer::FEConsumer | ( | int | sub_count, |
int | worker_count, | ||
int | high_watermark | ||
) |
Constructor.
Market data messages will be received, processed, and delivered by a pool of subscriber and worker threads.
Each subscriber thread will manage its own connection to the broadcast server. Whenever a subscription to a new topic is made, a subscriber is selected to handle that subscription on a round robin basis. Messages for a topic will always be received by the same subscriber thread to preserve proper ordering. Whenever a subscribe receives a message, that message is forwarded to a worker thread. The worker chosen to process the message will be consistent for a single topic.
Worker threads process the messages and then forward them to a notify queue registered with register_callback(). These messages can then be dispatched by dispatch() or dispatch_fd().
If the application is unable to process the messages fast enough, they will begin to queue up until the system runs out of memory. If this is undesirable, the high watermark can be set to drop messages once a certain amount have been queued.
sub_count | The number of subscriber threads to create. |
worker_count | The number of worker threads to create. |
high_watermark | The high watermark of the subscribers and workers. |
FactSet::Datafeed::FEConsumer::FEConsumer | ( | int | sub_count, |
int | worker_count | ||
) |
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
High watermark will be set to HWM_UNLIMITED.
Error FactSet::Datafeed::FEConsumer::authenticate | ( | const std::string & | host, |
const std::string & | user, | ||
const std::string & | serial, | ||
const std::string & | key_id, | ||
const std::string & | key, | ||
const std::string & | counter, | ||
const std::string & | path, | ||
bool | force_input | ||
) |
Authenticates with the given credentials.
A counter file will be created to store the key and counter used for authentication at the given path. This file will be named <key_id>.data. If a counter file already exists, the key and counter it contains will be used instead of the key and counter parameters. Setting the force_input flag to true will overwrite the counter file values with the given key and counter.
host | The address of the authentication server in the format host:port |
user | The name of the user |
serial | The serial associated with user |
key_id | The key id of the key being used for authenticated |
key | The key associated with key_id for user |
counter | The current counter for key |
path | The location to store the counter file |
force_input | If true, key and counter parameters will be used instead of the values in an existing counter file |
Error FactSet::Datafeed::FEConsumer::authenticate | ( | const std::string & | host, |
const std::string & | user, | ||
const std::string & | key_id, | ||
const std::string & | key, | ||
const std::string & | counter, | ||
const std::string & | path, | ||
bool | force_input | ||
) |
Authenticates with the given credentials.
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
host | The address of the authentication server in the format host:port |
user | The name and serial of the user in the format user-serial |
key_id | The key id of the key being used for authenticated |
key | The key associated with key_id for user |
counter | The current counter for key |
path | The location to store the counter file |
force_input | If true, key and counter parameters will be used instead of the values in an existing counter file |
void FactSet::Datafeed::FEConsumer::authenticate_async | ( | const std::string & | host, |
const std::string & | user, | ||
const std::string & | serial, | ||
const std::string & | key_id, | ||
const std::string & | key, | ||
const std::string & | counter, | ||
const std::string & | path, | ||
bool | force_input | ||
) |
void FactSet::Datafeed::FEConsumer::authenticate_async | ( | const std::string & | host, |
const std::string & | user, | ||
const std::string & | key_id, | ||
const std::string & | key, | ||
const std::string & | counter, | ||
const std::string & | path, | ||
bool | force_input | ||
) |
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
host | The address of the authentication server in the format host:port |
user | The name and serial of the user in the format user-serial |
key_id | The key id of the key being used for authenticated |
key | The key associated with key_id for user |
counter | The current counter for key |
path | The location to store the counter file |
force_input | If true, key and counter parameters will be used instead of the values in an existing counter file |
bool FactSet::Datafeed::FEConsumer::authenticated | ( | ) | const |
Authenticated state of the FEConsumer.
Error FactSet::Datafeed::FEConsumer::connect | ( | ) |
Connects to the broadcast server.
The FEConsumer must be authenticated before connecting.
void FactSet::Datafeed::FEConsumer::connect_async | ( | ) |
Connects to the broadcast server.
The FEConsumer must be authenticated before connecting.
bool FactSet::Datafeed::FEConsumer::connected | ( | ) | const |
Connected state of the FEConsumer.
The FEConsumer is only considered connected if it is connected to the data server on all channels. It is possible for this function to return false while data is still being received if only one channel is disconnected.
void FactSet::Datafeed::FEConsumer::disable_latency_tracking | ( | ) |
Disables tracking message latency throughout the consumer.
Error FactSet::Datafeed::FEConsumer::disconnect | ( | ) |
Disconnects from the broadcast server.
Closes the connection to the broadcast server by logging out if logged_in() and disconnecting. To reconnect after disconnecting, it is necessary to begin again at authentication.
The FEConsumer must be authenticated before connecting.
void FactSet::Datafeed::FEConsumer::disconnect_async | ( | ) |
Disconnects from the broadcast server.
Closes the connection to the broadcast server by logging out if logged_in() and disconnecting. To reconnect after disconnecting, it is necessary to begin again at authentication.
The FEConsumer must be authenticated before connecting.
Error FactSet::Datafeed::FEConsumer::dispatch | ( | long | timeout_ms | ) |
Convenience function for dispatching on all registered callbacks.
The file descriptors for each registered callback will be polled and dispatch_fd() will be called for each callback that has messages in its queue. If no messages are immediately available when this function is called, it will wait for up to timeout_ms milliseconds for messages to become available before returning. If a timeout occurs, this is not considered an error and Error::NoError will be returned.
timeout_ms | Number of milliseconds to wait before timing out. |
Error FactSet::Datafeed::FEConsumer::dispatch_fd | ( | SocketType | fd | ) |
Dispatches messages for the callback with the given file descriptor.
For each message in the notify queue for the callback with the given file descriptor, the associated callback that was registered by register_callback() will be called. This function should only be called on a readable file descriptor.
fd | File descriptor to dispatch. |
void FactSet::Datafeed::FEConsumer::enable_latency_tracking | ( | unsigned int | bucket_interval_sec | ) |
Enables tracking message latency throughout the consumer.
If enabled, the consumer will measure the latency for each message at various internal checkpoints. Two latencies will be tracked: one based on the MSG_GENESIS of the message (the time FactSet received the message from the exchange, referred to as the "real latency") and another based on the time the consumer received the message from the broadcast server (referred to as the "toolkit latency"). The highest latency observed during the bucket interval will be taken as the latency for that interval.The latencies at each checkpoint will be printed to the log at the end of the interval, in the following format: CheckpointName [Real Latency (Toolkit Latency)]
Checkpoints
Name | Description |
---|---|
Subscriber | The message was read off the socket from the broadcast server. |
Worker | The message was received by a worker thread. |
Callback Queue | The message was inserted into the matching callback queue. |
Dispatch | The callback for the message was called during dispatching. |
In addition to message latency, the consumer will also track the time it takes to call all callbacks during a call to dispatch() or dispatch_fd(). The longest of these durations within a bucket interval will be printed as the callback time.
All printed durations will be given in milliseconds.
bucket_interval_sec | The bucket interval in seconds. |
void FactSet::Datafeed::FEConsumer::event_cb | ( | EventCallback | callback | ) |
Sets the EventCallback() used for receiving events.
If the closure is set, then it will be returned in the callback, otherwise NULL will be returned.
callback | The EventCallback() to call when an event is received. |
void FactSet::Datafeed::FEConsumer::event_cb | ( | EventCallback | callback, |
void * | closure | ||
) |
Sets the EventCallback() used for receiving events.
If the closure is set, then it will be returned in the callback, otherwise NULL will be returned.
callback | The EventCallback() to call when an event is received. |
closure | The closure to return in the EventCallback() |
size_t FactSet::Datafeed::FEConsumer::get_notify_queue_message_limit | ( | ) |
Gets the notify queue message limit.
int FactSet::Datafeed::FEConsumer::get_notify_queue_time_limit_ms | ( | ) |
Gets the notify queue time limit.
Error FactSet::Datafeed::FEConsumer::get_notify_socket | ( | const std::string & | topic_prefix, |
SocketType & | fd_out | ||
) |
Returns the file descriptor for a given topic prefix.
The file descriptor returned will be the same value that was returned when the callback was initially registered.
topic_prefix | The topic prefix for which to retrieve the file descriptor. |
fd_out | On success, fd_out will be set to the file descriptor for the callback. |
unsigned int FactSet::Datafeed::FEConsumer::heartbeat_interval_sec | ( | ) | const |
Gets the seconds to wait to receive all snapshot messages before returning a timeout error.
void FactSet::Datafeed::FEConsumer::heartbeat_interval_sec | ( | unsigned int | seconds | ) |
Sets the seconds to wait between sending heartbeats.
seconds | The number of seconds to wait. |
unsigned int FactSet::Datafeed::FEConsumer::heartbeat_timeout_sec | ( | ) | const |
Gets the seconds to wait to receive a response after sending a heartbeat before considering the connection as timed out.
void FactSet::Datafeed::FEConsumer::heartbeat_timeout_sec | ( | unsigned int | seconds | ) |
Sets the seconds to wait to receive a response after sending a heartbeat before considering the connection as timed out.
seconds | The number of seconds to wait. |
bool FactSet::Datafeed::FEConsumer::is_subscribed | ( | const std::string & | topic | ) | const |
Checks for a subscription to a topic.
topic | The topic to check for subscribed status. |
Error FactSet::Datafeed::FEConsumer::log_in | ( | bool | request_files = true | ) |
Logs in to the broadcast server.
The FEConsumer must be connected before logging in.
void FactSet::Datafeed::FEConsumer::log_in_async | ( | bool | request_files = true | ) |
Logs in to the broadcast server.
The FEConsumer must be connected before logging in.
|
static |
Opens a file with the given filename to log messages from the toolkit.
filename | The name of the file to store the logs. |
append | If true, appends to previous log file instead of creating a fresh one. |
bool FactSet::Datafeed::FEConsumer::logged_in | ( | ) | const |
Login state of the FEConsumer.
unsigned int FactSet::Datafeed::FEConsumer::max_snapshot_queue_size | ( | ) | const |
Gets the maximum number of messages to hold for each topic while waiting for snapshots.
void FactSet::Datafeed::FEConsumer::max_snapshot_queue_size | ( | unsigned int | size | ) |
Sets the maximum number of messages to hold for each topic while waiting for snapshots.
When the maximum queue size is reached, older messages will be dropped in favor of new ones.
Error FactSet::Datafeed::FEConsumer::register_callback | ( | const std::string & | topic_prefix, |
FEConsumer::MessageCallback | callback, | ||
void * | closure, | ||
SocketType & | fd_out | ||
) |
Registers a callback for messages with topics starting with the given prefix.
For each registered callback, an internal notify queue will be created. The file descriptor returned in the parameter fd_out will become readable when a notify is triggered on this queue. A notify will be triggered after a certain number of messages have been enqueued or after a certain number of milliseconds have passed. After a notify is triggered, the file descriptor should not be read from directly. Rather, dispatch_fd() should be called to call the given FEConsumer::MessageCallback for each queued message.
topic_prefix | The topic prefix associated with this callback. |
callback | The FEConsumer::MessageCallback to call when dispatched. |
closure | The closure to return in the MessageCallback. |
fd_out | On success, fd_out will be set to the file descriptor for this callback. |
Error FactSet::Datafeed::FEConsumer::request_file | ( | const std::string & | filename, |
std::string & | contents_out | ||
) |
Requests a configuration file with a given name.
filename | The name of the file being requested. |
contents_out | The contents of the requested file or empty string if there was an error. |
void FactSet::Datafeed::FEConsumer::request_file_async | ( | const std::string & | filename | ) |
Requests a configuration file with a given name.
filename | The name of the file being requested. |
contents_out | The contents of the requested file or empty string if there was an error. |
|
static |
Sends logging messages to function instead of file/console.
callback | LoggingCallback to call on log message. |
void FactSet::Datafeed::FEConsumer::set_notify_queue_message_limit | ( | size_t | limit | ) |
Sets the notify queue message limit.
A notify queue that has not been notified will be notified when it contains at least as many messages as the limit.
limit | The message limit count. |
void FactSet::Datafeed::FEConsumer::set_notify_queue_time_limit_ms | ( | int | limit | ) |
Sets the notify queue time limit in milliseconds.
A notify queue that has not been notified will be notified when it contains at least 1 message and the time limit has passed.
unsigned int FactSet::Datafeed::FEConsumer::snapshot_timeout_sec | ( | ) | const |
Gets the seconds to wait to receive all snapshot messages before returning a timeout error.
void FactSet::Datafeed::FEConsumer::snapshot_timeout_sec | ( | unsigned int | seconds | ) |
Sets the seconds to wait to receive all snapshot messages before returning a timeout error.
seconds | The number of seconds to wait. |
Error FactSet::Datafeed::FEConsumer::stop | ( | ) |
Does nothing.
void FactSet::Datafeed::FEConsumer::stop_async | ( | ) |
Does nothing.
Error FactSet::Datafeed::FEConsumer::subscribe | ( | const std::string & | topic, |
SnapshotMode | snapshot_mode, | ||
DataMode | data_mode | ||
) |
Subscribes to a topic.
If snapshot messages were requested, all live data will be queued until all snapshots are received for the requested topic. If max_snapshot_queue_size() live data messages are queued before all snapshots are received, the oldest of the queued messages will be dropped in favor of newer messages. Once all snapshots are received, queued messages which are newer than the snapshots will be delivered via the registered callbacks as usual. Messages older than the snapshots will be dropped.
The format for the topic is productCode|issueType|isoCode|symbol. It is possible to subscribe to a prefix of the format, for example a subscription to a productCode|issueType|isoCode combination will subscribe to all symbols that match the combination. It is not possible to subscribe to two topics which overlap.
topic | The topic being subscribed. |
snapshot_mode | Determines whether or not snapshots will be requested. |
data_mode | Determines the type of data to request. |
void FactSet::Datafeed::FEConsumer::subscribe_async | ( | const std::string & | topic, |
SnapshotMode | snapshot_mode, | ||
DataMode | data_mode | ||
) |
unsigned int FactSet::Datafeed::FEConsumer::timeout_sec | ( | ) | const |
Gets the seconds to spend on a single command before returning a timeout error.
void FactSet::Datafeed::FEConsumer::timeout_sec | ( | unsigned int | seconds | ) |
Sets the seconds to spend on a single command before returning a timeout error.
Use NO_TIMEOUT to indicate infinite timeout.
seconds | The number of seconds to wait. |
Error FactSet::Datafeed::FEConsumer::unregister_callback | ( | const std::string & | topic_prefix | ) |
Unregisters a callback previously registered with register_callback().
topic_prefix | The topic prefix of the callback to unregister. |
Error FactSet::Datafeed::FEConsumer::unregister_callback | ( | SocketType | fd | ) |
Unregisters a callback previously registered with register_callback().
fd | The file descriptor of the callback to unregister. |
Error FactSet::Datafeed::FEConsumer::unsubscribe | ( | const std::string & | topic | ) |
Unsubscribes from a topic.
topic | The topic being unsubscribed. |
void FactSet::Datafeed::FEConsumer::unsubscribe_async | ( | const std::string & | topic | ) |
Unsubscribes from a topic.
topic | The topic being unsubscribed. |