Selecting securities of interest

By default, the handler processes market data for all securities in a particular market data channel. A considerable amount of data may cause the handler to allocate many system resources (like memory) for specific channels. On the other hand, applications often need data for only a subset of securities. The handler allows users to define a subset for which it monitors market data, maintains books, and reports other market-related events. The handler fires no events for any security that is not present in the defined subset. This feature is called selecting securities or security filtering.

The OnixS::CME::MDH::InstrumentSelection class must be used to gather securities for which the Handler must process market data.

If at least one security is added to the filter, the Handler stops raising events for all securities in the market data channel. Since that moment, the Handler fires events only for selected securities.

Securities can be filtered using security id, security group, symbol, and asset. For each attribute, the OnixS::CME::MDH::InstrumentSelection class exposes the corresponding member returning a collection of attribute values which can be manipulated as a regular std::set.

The security-ID, group, symbol and asset checks combine with AND: each populated collection must match the instrument. An empty collection imposes no restriction, so an entirely empty selection processes all securities on the channel.

For group, symbol and asset checks, an empty instrument attribute also passes the check even when the corresponding collection is populated. These attribute filters therefore do not exclude instruments whose definitions are missing. A security-ID selection still applies in that case; do not rely on a late definition to re-evaluate an existing instrument's selection.

Group filtering checks each instrument's own SecurityGroup, including strategies. It does not inspect strategy legs or automatically include related strategies. Check strategy definitions when choosing groups: strategies may belong to a different group from their legs.

A smaller selection can reduce book maintenance and callback work. It does not change the exchange's snapshot transmission cycle.

Note: Selecting securities affects the OnixS::CME::MDH::SecurityListener listener only. Other listeners are not affected by this feature.

Attention: Filtering must be manipulated only when the Handler is not processing market data and within the bounds of the HandlerListener::onEndOfInstrumentRecovery callback with a successful recovery status. Once the Handler begins market data processing or moves out of the noted callback scope, security selection must not be modified.

Example

The following code demonstrates how to instruct the Handler to process data only for selected securities:

class MySecuritySelector
    : public SecurityListener
    , public HandlerListener
{
public:
    void onDefinition(Handler&, const Security& security, const InstrumentDefinitionFutureArgs& args) override
    {
        if (userSelectedSecurity(args.message()))
            selection_.securityIds().insert(security.id());
    }
 
    void onDefinition(Handler&, const Security& security, const InstrumentDefinitionSpreadArgs& args) override
    {
        if (userSelectedSecurity(args.message()))
            selection_.securityIds().insert(security.id());
    }
 
    void onDefinition(Handler&, const Security& security, const InstrumentDefinitionOptionArgs& args) override
    {
        if (userSelectedSecurity(args.message()))
            selection_.securityIds().insert(security.id());
    }
 
    void onEndOfInstrumentRecovery(Handler& handler, const RecoveryCompletionArgs& args) override
    {
        if (RecoveryCompletionStatus::Succeeded == args.status())
            handler.selectInstruments(selection_);
    }
 
private:
    InstrumentSelection selection_;
};
 
Handler handler;
 
MySecuritySelector selector;
 
handler.settings().listeners().security(&selector).handler(&selector);
 
handler.start();