Pages/SelectingSecuritiesOfInterest.md

Go to the documentation of this file.

\addtogroup security-selection 

\brief Provides information on how to make Handler raise 
security-related events for particular securities only. 

\section define-security-selection Defining Securities of Interest

By default, the Handler processes market data for all securities available 
in a particular market data channel. For certain channels, it may be a huge 
amount of data which may cause the Handler to allocate a significant amount 
of system resources (like a memory). From the other side, it often happens 
that not all securities are the point of interest. For these reasons, the 
Handler provides an ability to define a subset of securities for which it 
monitors market data, maintains books and report about other market-related 
events. The Handler fires no events for any security not present in the 
defined subset. This feature is called *selecting securities or security 
filtering*.

Selecting securities is similar to the process of filling a bag with 
apples. The OnixS::CME::MDH::InstrumentSelection class must be used to 
gather securities into a collection for which the Handler must process 
market data. There're no limits on the quantity of securities which can 
be included into the selection.

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

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

An empty (blank) security selection causes the Handler to process 
market data and to trigger events for all securities on the channel.

\note Selecting securities affects the OnixS::CME::MDH::SecurityListener 
listener only. The Handler does not invoke listener members for securities 
out of the selection scope. Other listeners are not affected by this feature.

\warning **Filtering must be manipulated only when the 
Handler is not processing market data or in bounds of the 
OnixS::CME::MDH::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.**

\section security-filter-example Example

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

~~~{.cpp}

using namespace OnixS::CME::MDH;

class
InteractiveSecuritySelector
: public SecurityListener
, public HandlerListener
{
    InstrumentSelection selection_;

    template
    <
        class Definition
    >
    bool
    userSelectedSecurity(
        const Definition& definition)
    {
        // Given member asks user whether user wants
        // to have market data for given instrument.
        // Returned value indicates whether user
        // selected instrument.

        return true;
    }

public:
    InteractiveSecuritySelector()
    {
    }

    void
    onDefinition(
        Handler&,
        const Security& security,
        const InstrumentDefinitionFutureArgs& args)
    {
        if (userSelectedSecurity(args.message())
            selection_.securityIds().insert(security.id());
    }

    void
    onDefinition(
        Handler&,
        const Security& security,
        const InstrumentDefinitionSpreadArgs& args)
    {
        if (userSelectedSecurity(args.message())
            selection_.securityIds().insert(security.id());
    }

    void
    onDefinition(
        Handler&,
        const Security& security,
        const InstrumentDefinitionOptionArgs& args)
    {
        if (userSelectedSecurity(args.message())
            selection_.securityIds().insert(security.id());
    }

    void
    onEndOfInstrumentRecovery(
        Handler& handler,
        const RecoveryCompletionArgs& args)
    {
        if (args.status() ==
            RecoveryCompletionStatus::Succeeded)
        {
            handler.selectInstruments(selection_);
        }
    }
};

Handler handler(settings);

InteractiveSecuritySelector selector;

handler.registerSecurityListener(selector);
handler.registerListener(selector);

handler.start();

~~~