SessionSettings.h

Go to the documentation of this file.

// Copyright Onix Solutions Limited [OnixS]. All rights reserved.
//
// This software owned by Onix Solutions Limited [OnixS] and is 
// protected by copyright law and international copyright treaties.
//
// Access to and use of the software is governed by the terms of the applicable 
// OnixS Software Services Agreement (the Agreement) and Customer end user license 
// agreements granting a non-assignable, non-transferable and non-exclusive license 
// to use the software for it's own data processing purposes under the terms defined 
// in the Agreement.
//
// Except as otherwise granted within the terms of the Agreement, copying or 
// reproduction of any part of this source code or associated reference material 
// to any other location for further reproduction or redistribution, and any 
// amendments to this copyright notice, are expressly prohibited.
//
// Any reproduction or redistribution for sale or hiring of the Software not in 
// accordance with the terms of the Agreement is a violation of copyright law.
//

#pragma once

#include <string>

#include <OnixS/CME/ConflatedUDP/Integral.h>
#include <OnixS/CME/ConflatedUDP/SettingGroup.h>

ONIXS_CONFLATEDUDP_NAMESPACE_BEGIN

/// Defines type of recovery to be done 
/// by Handler at the time it joins market. 
ONIXS_CONFLATEDUDP_LTWT_STRUCT 
JoinRecoveryOptions
{
    /// Integral type serving as 
    /// basement for given enumeration. 
    typedef UInt32 Base;

    /// Defines type of recovery to be done 
    /// by Handler while it joins market. 
    enum Enum
    {
        /// No recovery is to be done at join time. 
        /// Handler will switch to real-time data 
        /// processing immediately. 
        Disabled,

        /// Instructs Handler to recover instruments before 
        /// switching to real-time (incremental data) processing.
        Instruments,

        /// Instructs Handler to perform full recovery (both instruments 
        /// and market state (books, last trades, statistics, etc))
        /// before switching to real-time (incremental) data processing.
        InstrumentsAndMarketState
    };
};

/// Serializes join recovery option. 
ONIXS_CONFLATEDUDP_EXPORTED
void
toStr(
    std::string&, 
    JoinRecoveryOptions::Enum);

/// Serializes join recovery option. 
inline
std::string
toStr(
    JoinRecoveryOptions::Enum recovery)
{
    std::string str;
    
    toStr(str, recovery);
    
    return str;
}

/// Defines the way Handler has to handle 
/// gap in real-time (incremental) data. 
ONIXS_CONFLATEDUDP_LTWT_STRUCT 
GapAndErrorHandlingOptions
{
    /// Integral type serving as 
    /// basement for given enumeration. 
    typedef UInt32 Base;

    /// Defines the way Handler has to handle 
    /// gap in real-time (incremental) data. 
    enum Enum
    {
        /// Handler recovers market state from snapshots.
        RecoverMarketState,

        /// Handler recovers instruments and market state afterwards. 
        RecoverInstrumentsAndMarketState,

        /// Handler continues processing of real-time market data. 
        ContinueProcessing
    };
};

/// Serializes gap and error handling option. 
ONIXS_CONFLATEDUDP_EXPORTED
void
toStr(
    std::string&, 
    GapAndErrorHandlingOptions::Enum);

/// Serializes gap and error handling option. 
inline
std::string
toStr(
    GapAndErrorHandlingOptions::Enum handling)
{
    std::string str;
    
    toStr(str, handling);
    
    return str;
}

/// Defines different ways of instrument definition recovery.
ONIXS_CONFLATEDUDP_LTWT_STRUCT 
InstrumentRecoveryOptions
{
    /// Integral type used as basement for constants. 
    typedef UInt32 Base;

    enum Enum
    {
        /// The given strategy tells the Handler to recover instruments 
        /// in the most accurate way. In particular, the Handler processes 
        /// instrument definitions from the beginning of a recovery loop. 
        /// If the Handler joins instrument recovery feed in the middle 
        /// of a recovery loop, incoming data is ignored until a new loop 
        /// begins. Also, if the Handler detects gap in a sequence of 
        /// incoming packets, it will stop processing instrument definitions 
        /// till the end of a loop and restart the recovery from the beginning 
        /// of a new loop. 
        /// The given way to recover instruments is highly recommended for 
        /// the channels, where user-defined instruments are frequently added 
        /// or removed during the trading week. 
        /// Accurate recovery may take longer due to necessity to wait for 
        /// the beginning of a new loop caused by join at the middle of a 
        /// prior loop or data loss.
        Accurate,

        /// The fast mode allows to start processing instrument definitions 
        /// from the middle of a recovery loop without waiting for the beginning 
        /// of the next loop. In case of data loss, missing definitions are 
        /// recovered from the next loops. The given approach allows to recover
        /// quickly. However, the recovered set of instruments may not be accurate 
        /// because of differences in the recovery loops from where the recovery 
        /// data was taken.
        Fast
    };
};

/// Serializes instrument definition recovery strategy.
ONIXS_CONFLATEDUDP_EXPORTED
void
toStr(
    std::string&,
    InstrumentRecoveryOptions::Enum);

/// Serializes instrument definition recovery strategy.
inline 
std::string
toStr(
    InstrumentRecoveryOptions::Enum option)
{
    std::string str;

    toStr(str, option);

    return str;
}

ONIXS_CONFLATEDUDP_EXPORTED_CLASS_DECL
(
    TcpRecoveryService
);

/// Collection of session settings related to TCP recovery. 
ONIXS_CONFLATEDUDP_LTWT_CLASS 
TcpRecoverySessionSettings
{
    /// Lets grouping and value assignment control functioning. 
    friend 
    ONIXS_CONFLATEDUDP_LTWT_CLASS_DECL
    (
        AdvancedSessionSettings
    );

    //

    const SettingGroup& group_;

    TcpRecoveryService* service_;

    UInt32 attempts_;
    UInt32 servingTimeLimit_;

    // Re-initializes the instance as a copy of the 
    // other one and bypassing assignment control. 
    void
    assignNoControl(
        const 
        TcpRecoverySessionSettings& other)
    {
        service_ = 
            other.service_;

        attempts_ = 
            other.attempts_;

        servingTimeLimit_ = 
            other.servingTimeLimit_;
    }

public:
    /// Initializes the instance with the default values. 
    /// 
    /// Optional group parameter lets to make the  
    /// instance belonging to a given group of settings. 
    TcpRecoverySessionSettings(
        const SettingGroup* group = NULL)
        : group_(
            group 
            ? *group 
            : SettingGroup::null())
        , service_(NULL)
        , attempts_(1)
        , servingTimeLimit_(10)
    {
    }

    /// Initializes the instance as a copy 
    /// of the other one. Grouping and value 
    /// assignment control services are not 
    /// copied. 
    TcpRecoverySessionSettings(
        const TcpRecoverySessionSettings& other)
        : group_(SettingGroup::null())
        , service_(other.service_)
        , attempts_(other.attempts_)
        , servingTimeLimit_(
            other.servingTimeLimit_)
    {
    }

    /// Finalizes the instance.
    ~TcpRecoverySessionSettings()
    {
    }

    /// An instance of the TCP recovery 
    /// service if there's any associated. 
    /// 
    /// Null instance indicates no service is 
    /// associated and thus TCP recovery is disabled 
    /// during market data processing session. 
    TcpRecoveryService* 
    service() const
    {
        return service_;
    }

    /// Associates the instance of the TCP Recovery 
    /// service to be used by a Handler during market 
    /// data processing session. 
    void
    service(
        TcpRecoveryService* service)
    {
        group_.
            controlAssignment
            (
                "TCP Recovery Service Instance", 
                service_, 
                service
            );
    }

    /// Number of times a Handler must try to recover 
    /// missing data using the TCP recovery before it 
    /// switches to recover market state from snapshots 
    /// or resumes incremental data processing by natural 
    /// refresh. 
    UInt32
    attempts() const
    {
        return attempts_;
    }

    /// Updates number of times a Handler must try 
    /// to recover missing data using the TCP recovery 
    /// before it switches to recover market state from
    /// snapshots or resumes incremental data processing 
    /// by natural refresh. 
    void
    attempts(
        UInt32 qty)
    {
        group_.
            controlAssignment
            (
                "TCP Recovery Attempt Quantity", 
                attempts_,
                qty
            );
    }

    /// Amount of time allocated to process a 
    /// recovery request. TCP recovery service 
    /// interrupts request processing if it can't 
    /// be accomplished within given time frame.
    ///
    /// Interval is measured in seconds. 
    ///
    /// @note Default value is '10'. 
    UInt32 
    servingTimeLimit() const
    {
        return servingTimeLimit_;
    }

    /// Amount of time allocated to process a 
    /// recovery request. TCP recovery service 
    /// interrupts request processing if it can't 
    /// be accomplished within given time frame.
    ///
    /// Interval is measured in seconds. 
    void 
    servingTimeLimit(
        UInt32 servingTimeLimit)
    {
        group_.
            controlAssignment
            (
                "TCP Recovery Serving Time Limit", 
                servingTimeLimit_,
                servingTimeLimit
            );
    }

    /// Re-initializes as a copy of the other one. Grouping 
    /// and value assignment control services aren't copied. 
    TcpRecoverySessionSettings&
    operator =(
        const 
        TcpRecoverySessionSettings& other)
    {
        group_.
            controlAssignment
            (
                "TCP Recovery Session Settings",
                &TcpRecoverySessionSettings::assignNoControl,
                *this,
                other
            );

        return *this;
    }
};

/// Serializes market recovery option. 
ONIXS_CONFLATEDUDP_EXPORTED
void
toStr(
    std::string&,
    const 
    TcpRecoverySessionSettings&);

/// Serializes market recovery option. 
inline 
std::string
toStr(
    const 
    TcpRecoverySessionSettings& settings)
{
    std::string str;

    toStr(str, settings);

    return str;
}

/// Basic set of parameters affecting behavior of the 
/// Handler when the market data processing is performed. 
/// 
/// @note The given class exists to provide backward compatibility 
/// with the previous releases. Use 'AdvancedSessionSettings' instead.
ONIXS_CONFLATEDUDP_LTWT_CLASS SessionSettings : public SettingGroup
{
    JoinRecoveryOptions::Enum joinRecovery_;
    GapAndErrorHandlingOptions::Enum gapAndErrorHandling_;
    
    InstrumentRecoveryOptions::Enum instrumentRecovery_;

protected:
    /// Instance of the group to which 
    /// the given settings belongs. 
    const 
    SettingGroup& 
    group() const
    {
        return *this;
    }

    /// Re-initializes the instance as a copy of the 
    /// other one and bypassing assignment control. 
    void
    assignNoControl(
        const SessionSettings& other)
    {
        joinRecovery_ = 
            other.joinRecovery_;
        
        gapAndErrorHandling_ = 
            other.gapAndErrorHandling_;

        instrumentRecovery_ = 
            other.instrumentRecovery_;
    }

public:
    /// Initializes parameters with default values.
    SessionSettings(
        SettingAssignController* 
        controller = NULL)
        : SettingGroup(controller) 
        , joinRecovery_(
            JoinRecoveryOptions::
                InstrumentsAndMarketState)
        , gapAndErrorHandling_(
            GapAndErrorHandlingOptions::
                RecoverMarketState)
        , instrumentRecovery_(
            InstrumentRecoveryOptions::
            Accurate)
    {
    }

    /// Re-initializes settings as copies of 
    /// the other ones omitting group belonging.
    SessionSettings(
        const SessionSettings& other)
        : SettingGroup()
        , joinRecovery_(
            other.joinRecovery_)
        , gapAndErrorHandling_(
            other.gapAndErrorHandling_)
        , instrumentRecovery_(
            other.instrumentRecovery_)
    {
    }

    /// Cleans everything up.
    ~SessionSettings()
    {
    }

    /// Defines aspects of recovery 
    /// to be done at market join stage. 
    /// 
    /// @note Default value is 
    /// JoinRecovery::InstrumentsAndMarket. 
    JoinRecoveryOptions::Enum 
    joinRecovery() const
    {
        return joinRecovery_;
    }

    /// Defines aspects of recovery 
    /// to be done at market join stage. 
    void 
    joinRecovery(
        JoinRecoveryOptions::Enum recovery)
    {
        group().
            controlAssignment
            (
                "Join Recovery Strategy", 
                joinRecovery_, 
                recovery
            );
    }

    /// Defines what Handler should do in case 
    /// of gap in real-time (incremental) data. 
    ///
    /// @note Default value is 
    /// GapAndErrorHandling::RecoverMarketState.
    GapAndErrorHandlingOptions::Enum 
    gapAndErrorHandling() const
    {
        return gapAndErrorHandling_;
    }

    /// Defines what Handler should do in case 
    /// of gap in real-time (incremental) data. 
    void 
    gapAndErrorHandling(
        GapAndErrorHandlingOptions::Enum handling)
    {
        group().
            controlAssignment
            (
                "Gap And Error Handling Strategy",
                gapAndErrorHandling_,
                handling
            );
    }

    /// Indicates how instrument definitions are recovered.
    /// 
    /// @note Default value is InstrumentRecoveryOptions::Accurate.
    InstrumentRecoveryOptions::Enum
    instrumentRecovery() const
    {
        return instrumentRecovery_;
    }

    /// Defines how instrument definitions are recovered.
    void 
    instrumentRecovery(
        InstrumentRecoveryOptions::Enum recovery)
    {
        group().
            controlAssignment
            (
                "Instrument Recovery Strategy", 
                instrumentRecovery_,
                recovery
            );
    }

    /// Copies settings from the given instance. 
    /// 
    /// Attributes controlling value assignment aren't 
    /// cloned and thus only settings' values are copied. 
    SessionSettings&
    operator =(
        const SessionSettings& other)
    {
        group().
            controlAssignment
            (
                "Session Settings",
                &SessionSettings::assignNoControl,
                *this,
                other
            );

        return *this;
    }
};

/// Serializes market data processing session settings. 
ONIXS_CONFLATEDUDP_EXPORTED
void
toStr(
    std::string&, 
    const SessionSettings&);

/// Serializes market data processing session settings. 
inline
std::string
toStr(
    const SessionSettings& settings)
{
    std::string str;
    
    toStr(str, settings);

    return str;
}

/// Full set of parameters affecting behavior 
/// of the Handler when market data is processed.
ONIXS_CONFLATEDUDP_LTWT_CLASS 
AdvancedSessionSettings 
    : public SessionSettings
{
    // Lets grouping and value assignment control functioning. 
    friend ONIXS_CONFLATEDUDP_LTWT_CLASS_DECL(HandlerSettings);

    TcpRecoverySessionSettings tcpRecovery_;

    // Re-initializes the instance as a copy of the 
    // other one and bypassing assignment control. 
    void
    assignNoControl(
        const AdvancedSessionSettings& other)
    {
        SessionSettings::assignNoControl(other);

        tcpRecovery_.assignNoControl(other.tcpRecovery_);
    }

public:
    /// Initializes parameters with default values.
    AdvancedSessionSettings(
        SettingAssignController* 
        controller = NULL)
        : SessionSettings(controller) 
        , tcpRecovery_(&group())
    {
    }

    /// Re-initializes settings as copies of 
    /// the other ones omitting group belonging.
    AdvancedSessionSettings(
        const AdvancedSessionSettings& other)
        : SessionSettings(
            static_cast
            <const SessionSettings&>
            (other))
        , tcpRecovery_(
            other.tcpRecovery_)
    {
    }

    /// Cleans everything up.
    ~AdvancedSessionSettings()
    {
    }

    /// Set of TCP recovery settings.
    const 
    TcpRecoverySessionSettings&
    tcpRecovery() const
    {
        return tcpRecovery_;
    }

    /// Editable set of TCP recovery settings.
    TcpRecoverySessionSettings&
    tcpRecovery()
    {
        return tcpRecovery_;
    }

    /// Copies settings from the given instance. 
    /// 
    /// Attributes controlling value assignment aren't 
    /// cloned and thus only settings' values are copied. 
    AdvancedSessionSettings&
    operator =(
        const AdvancedSessionSettings& other)
    {
        group().
            controlAssignment
            (
                "Advanced Session Settings",
                &AdvancedSessionSettings::assignNoControl,
                *this,
                other
            );

        return *this;
    }
};

/// Serializes market data processing session settings. 
ONIXS_CONFLATEDUDP_EXPORTED
void
toStr(
    std::string&, 
    const AdvancedSessionSettings&);

/// Serializes market data processing session settings. 
inline
std::string
toStr(
    const 
    AdvancedSessionSettings& settings)
{
    std::string str;
    
    toStr(str, settings);

    return str;
}

// Various functions helping in configuring session in the desired way. 

/// Updates session settings to tell the Handler 
/// to recover instruments using accurate strategy 
/// each time instrument recovery is performed. 
inline 
void
setSessionToRecoverInstrumentsAccurately
(
    SessionSettings& settings
)
{
    settings.
        instrumentRecovery(
            InstrumentRecoveryOptions::
            Accurate);
}

/// Updates session settings to tell the Handler 
/// to recover instruments using fast strategy each 
/// time instrument recovery is performed. 
inline 
void
setSessionToRecoverInstrumentsFast
(
    SessionSettings& settings
)
{
    settings.
        instrumentRecovery(
            InstrumentRecoveryOptions::
            Fast);
}

/// Updates session settings to tell the Handler 
/// to skip join-time recovery and switch processing 
/// incremental (real-time) data. 
inline 
void
setSessionToJoinInPreopening
(
    SessionSettings& settings
)
{
    settings.
        joinRecovery(
            JoinRecoveryOptions::
            Disabled);
}

/// Updates session settings to tell the Handler 
/// to recover instruments and market state before 
/// it switches processing incremental data. 
inline 
void
setSessionToLateJoin(
    SessionSettings& settings)
{
    settings.
        joinRecovery(
            JoinRecoveryOptions::
            InstrumentsAndMarketState);
}

/// Updates session settings to tell the 
/// Handler to recover instruments and market 
/// state (books) in case of gap or other issue. 
inline
void
setSessionToFullRecoverUponRealtimeIssues
(
    SessionSettings& settings
)
{
    settings.
        gapAndErrorHandling(
            GapAndErrorHandlingOptions::
            RecoverInstrumentsAndMarketState);
}

/// Updates session settings to tell the 
/// Handler to recover market state (books) 
/// in case of gap or other issue. 
inline
void
setSessionToRecoverBooksUponRealtimeIssues
(
    SessionSettings& settings
)
{
    settings.
        gapAndErrorHandling(
            GapAndErrorHandlingOptions::
            RecoverMarketState);
}

/// Updates session settings to tell the Handler 
/// continue processing incremental (real-time) 
/// data in case of gap or other issue. 
inline
void
setSessionToContinueRealtimeProcessingUponIssues
(
    SessionSettings& settings
)
{
    settings.
        gapAndErrorHandling(
            GapAndErrorHandlingOptions::
            ContinueProcessing);
}

// Complex (one-call) setup. 

/// Configures session to maintain order books 
/// accurately and without performing initial 
/// (late-join) recovery thus considering market 
/// data processing is started from the beginning 
/// of weekly session. 
inline 
void
setSessionToAccuratePreopening
(
    SessionSettings& settings
)
{
    setSessionToRecoverInstrumentsAccurately
    (
        settings
    );
    setSessionToJoinInPreopening
    (
        settings
    );
    setSessionToRecoverBooksUponRealtimeIssues
    (
        settings
    );
}

/// Configures session to maintain order 
/// books accurately and considering market 
/// data processing is started at the middle 
/// of weekly session (late join). 
inline
void
setSessionToAccurateLateJoin
(
    SessionSettings& settings
)
{
    setSessionToRecoverInstrumentsAccurately
    (
        settings
    );
    setSessionToLateJoin
    (
        settings
    );
    setSessionToRecoverBooksUponRealtimeIssues
    (
        settings
    );
}

/// Configures session settings to maintain 
/// order books using natural refresh. Startup 
/// recovery is not performed and thus only 
/// real-time processing takes place. 
inline 
void
setSessionToNaturalRefresh(
    SessionSettings& settings)
{
    setSessionToJoinInPreopening
    (
        settings
    );
    setSessionToContinueRealtimeProcessingUponIssues
    (
        settings
    );
}

// Deprecated way of session setup. 

#if !defined (ONIXS_CONFLATEDUDP_NO_DEPRECATED)

/// Settings for session with accurate book 
/// maintenance and considering market data 
/// processing is started from the beginning 
/// of weekly session. 
ONIXS_CONFLATEDUDP_LTWT_STRUCT
AccuratePreopeningSession
: SessionSettings
{
    /// Configures session settings 
    /// according to specialization.
    AccuratePreopeningSession()
    {
        setSessionToAccuratePreopening(*this);
    }
};

/// Settings for session with accurate book 
/// maintenance and considering market data 
/// processing is started at the middle of 
/// weekly session (late join). 
ONIXS_CONFLATEDUDP_LTWT_STRUCT 
AccurateLateJoinSession
: SessionSettings
{
    /// Configures session settings 
    /// according to specialization.
    AccurateLateJoinSession()
    : SessionSettings()
    {
        setSessionToAccurateLateJoin(*this);
    }
};

/// Configures session settings to maintain 
/// order books using natural refresh. Startup 
/// recovery is not performed and thus only 
/// real-time processing takes place. 
ONIXS_CONFLATEDUDP_LTWT_STRUCT
NaturalRefreshSession
: SessionSettings
{
    /// Configures session settings 
    /// according to specialization.
    NaturalRefreshSession()
    : SessionSettings()
    {
        setSessionToNaturalRefresh(*this);
    }
};

#endif // ONIXS_CONFLATEDUDP_NO_DEPRECATED

ONIXS_CONFLATEDUDP_NAMESPACE_END