FeedEngine.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 <OnixS/Euronext/MarketData/OptiqMdg/ABI.h>
#include <OnixS/Euronext/MarketData/OptiqMdg/Integral.h>
#include <OnixS/Euronext/MarketData/OptiqMdg/Defines.h>
#include <OnixS/Euronext/MarketData/OptiqMdg/WatchService.h>

#include <string>

namespace OnixS
{
    namespace Euronext
    {
        namespace MarketData
        {
            namespace OptiqMdg
            {
                /// Designed to reflect various aspects of feed engine processing flow.
                class NetFeedEngineProcessResult
                {
                public:
                    /// Aliases integral type whose bits are used to indicate flag presence.
                    typedef UInt32 Flags;

                    ///
                    explicit NetFeedEngineProcessResult(UInt32 flags) ONIXS_EURONEXT_OPTIQMDG_NOTHROW
                    {
                        value_.raw_ = flags;
                    }

                    /// Indicates whether feed-related events like data reception or absence have been dispatched.
                    bool eventsDispatched() const ONIXS_EURONEXT_OPTIQMDG_NOTHROW
                    {
                        return 0 != value_.bits_.eventsDispatched_;
                    }

                    /// Indicates whether feed-related events like data reception or absence have been dispatched.
                    void eventsDispatched(bool state) ONIXS_EURONEXT_OPTIQMDG_NOTHROW
                    {
                        value_.bits_.eventsDispatched_ = state ? 1 : 0;
                    }

                    /// Indicates whether processing had to sleep in kernel while checking data availability.
                    bool ioWaited() const ONIXS_EURONEXT_OPTIQMDG_NOTHROW
                    {
                        return 0 != value_.bits_.ioWaited_;
                    }

                    /// Indicates whether processing had to sleep in kernel while checking data availability.
                    void ioWaited(bool state) ONIXS_EURONEXT_OPTIQMDG_NOTHROW
                    {
                        value_.bits_.ioWaited_ = state ? 1 : 0;
                    }

                    /// Reserved (unused) flags.
                    Flags reserved() const ONIXS_EURONEXT_OPTIQMDG_NOTHROW
                    {
                        return value_.bits_.reserved_;
                    }

                    /// Reserved (unused) flags.
                    void reserved(Flags flags) ONIXS_EURONEXT_OPTIQMDG_NOTHROW
                    {
                        value_.bits_.reserved_ = flags;
                    }

                private:
                    struct Bitset
                    {
                        Flags eventsDispatched_ : 1;
                        Flags ioWaited_         : 1;
                        Flags reserved_         : 30;
                    };

                    union Value
                    {
                        Bitset bits_;
                        Flags raw_;
                    };

                    Value value_;
                };

                /// The Feed Engine machinery
                class ONIXS_EURONEXT_OPTIQMDG_API FeedEngine
                {
                public:
                    /// Carries out pending actions like data retrieval and event dispatching.
                    /// This function must be invoked after each handler-associated action (i.e., start, stop).
                    NetFeedEngineProcessResult process();

                    /// Provides information about the actual implementation of the feed engine.
                    std::string info();

                    ///
                    virtual ~FeedEngine();

                protected:
                    explicit FeedEngine(void* impl);

                private:
                    FeedEngine(const FeedEngine&);
                    FeedEngine& operator=(const FeedEngine&);

                    void* const impl_;
                    friend struct FeHelper;
                };

                /// Carries out pending actions like
                /// data retrieval and event dispatching.
                ///
                /// The returned value indicates whether any
                /// events have been handled by the engine.
                inline bool process(FeedEngine& engine)
                {
                    return engine.process().eventsDispatched();
                }

                /// The given class implements feed engine concept using pool of working threads and standard socket API.
                class ONIXS_EURONEXT_OPTIQMDG_API SocketFeedEngine : public FeedEngine
                {
                public:
                    /// Constructor
                    /// \param socketBufferSize Defines size of receiving buffer in bytes for sockets.
                    /// \param dataWaitTime Defines amount of time Feed Engine spends on
                    /// waiting for I/O while running master processing loop. Time is measured in milliseconds.
                    ///
                    /// \param watch Watch service to be used by Feed Engine.
                    ///
                    /// Watch is used by Feed Engine to assign time
                    /// points to packets received from the feeds.
                    ///
                    /// @note By default, Utc watch service is used.
                    explicit SocketFeedEngine(
                        UInt32 dataWaitTime = 10, UInt32 socketBufferSize = 8 * 1024 * 1024, WatchService& watch = UtcWatch::service());

                    ///
                    ~SocketFeedEngine() ONIXS_EURONEXT_OPTIQMDG_OVERRIDE;
                };

                /// The given class implements the Feed Engine concept using the Solarlfare ef_vi SDK.
                class ONIXS_EURONEXT_OPTIQMDG_API EfViFeedEngine : public FeedEngine
                {
                public:
                    /// Constructor
                    /// \param receiveRingSize Number of buffers in a virtual interface receive ring.
                    /// Single buffer is used for a single network packet.
                    /// Thus the receive ring must be capacious enough to
                    /// place incoming packets during market data bursts.
                    ///
                    /// \param watch Watch service to be used by Feed Engine.
                    ///
                    /// Watch is used by Feed Engine to assign time
                    /// points to packets received from the feeds.
                    ///
                    /// @note By default, NIC watch service is used.
                    explicit EfViFeedEngine(UInt32 receiveRingSize = 4095, WatchService& watch = NicWatch::service());

                    ///
                    ~EfViFeedEngine() ONIXS_EURONEXT_OPTIQMDG_OVERRIDE;
                };

                /// Identifies reasons feed engine threads becomes idle.
                struct FeedEngineThreadIdle
                {
                    enum Reason
                    {
                        /// Thread waited for incoming data using corresponding
                        /// I/O operations (like 'select') and exited waiting with
                        /// no data availability signs.
                        DataWaitTimeout,

                        /// Thread entered idle state due to absence of any data and
                        /// while other threads are waiting for new incoming data.
                        Redundant
                    };
                };

                ///
                struct FeedEngineThreadPoolSettings
                {
                    FeedEngineThreadPoolSettings()
                      : threadAffinity_()
                      , spinBeforeIdleTime_(1)
                      , threadCount_(1)
                    {
                    }

                    /// Defines set of CPUs allowed for each working thread
                    /// to be executed on while processing market data by Handlers
                    /// bound to Feed Engine instance which is configured by given
                    /// settings.
                    ///
                    /// @note By default set is empty thus allowing threads
                    /// to be executed on any CPU available in the system.
                    const ThreadAffinity& threadAffinity() const
                    {
                        return threadAffinity_;
                    }

                    /// Defines set of CPUs allowed for each working thread
                    /// to be executed on while processing market data by Handlers
                    /// bound to Feed Engine instance which is configured by given
                    /// settings.
                    ///
                    /// @note By default set is empty thus allowing threads
                    /// to be executed on any CPU available in the system.
                    ThreadAffinity& threadAffinity()
                    {
                        return threadAffinity_;
                    }

                    /// Number of working threads to be used by feed engine.
                    ///
                    /// @note Default value is '1'.
                    UInt32 threadCount() const
                    {
                        return threadCount_;
                    }

                    /// Sets threadsCount. @see threadsCount.
                    void threadCount(UInt32 value)
                    {
                        threadCount_ = value;
                    }

                    /// Defines amount of time Feed Engine keeps cycling before
                    /// going to sleep when no useful activity can be done.
                    ///
                    /// Time is measured in milliseconds.
                    ///
                    /// @note Default value is '1'.
                    ///
                    /// @warning Given parameter has direct influence onto CPU load!
                    UInt32 spinBeforeIdleTime() const
                    {
                        return spinBeforeIdleTime_;
                    }

                    /// Sets redundancySpinTime. @see redundancySpinTime.
                    void spinBeforeIdleTime(UInt32 value)
                    {
                        spinBeforeIdleTime_ = value;
                    }

                private:
                    ThreadAffinity threadAffinity_;
                    UInt32 spinBeforeIdleTime_;
                    UInt32 threadCount_;
                };

                class ONIXS_EURONEXT_OPTIQMDG_API FeedEngineThreadPool;

                /// Listener for thread-related events.
                ///
                /// Members of this classes are invoked to reflect
                /// various life-time events of threads spawned and
                /// used by the feed engine while processing market data.
                struct ONIXS_EURONEXT_OPTIQMDG_API FeedEngineThreadPoolListener
                {
                    /// Member invoked by feed engine when
                    /// a new processing thread is spawned.
                    ///
                    /// @note Invocation is done within newly
                    /// started thread.
                    virtual void onFeedEngineThreadBegin(const FeedEngineThreadPool&) {}

                    /// Member is invoked by feed engine when
                    /// processing thread is about to end.
                    ///
                    /// @note Invocation is done within the
                    /// thread that is about to end.
                    virtual void onFeedEngineThreadEnd(const FeedEngineThreadPool&) {}

                    /// Is called when feed engine's thread is idle.
                    ///
                    /// Integer parameter-variable defines amount of time feed engine
                    /// suggest for thread to sleep in kernel after invoking given member.
                    virtual void onFeedEngineThreadIdle(const FeedEngineThreadPool&, FeedEngineThreadIdle::Reason, UInt32&) {}

                    ///
                    virtual ~FeedEngineThreadPoolListener() {}
                };

                /// A pool of threads executing feed engine tasks.
                class ONIXS_EURONEXT_OPTIQMDG_API FeedEngineThreadPool
                {
                public:
                    FeedEngineThreadPool(
                        const FeedEngineThreadPoolSettings&, FeedEngine*, FeedEngineThreadPoolListener* = ONIXS_EURONEXT_OPTIQMDG_NULLPTR);

                    ~FeedEngineThreadPool();

                    const FeedEngineThreadPoolSettings settings() const;

                private:
                    FeedEngineThreadPool(const FeedEngineThreadPool&);
                    FeedEngineThreadPool& operator=(const FeedEngineThreadPool&);

                    const FeedEngineThreadPoolSettings settings_;
                    class FeedEngineThreadPoolImpl;
                    FeedEngineThreadPoolImpl* impl_;
                };

                /// Current thread related tasks.
                class ONIXS_EURONEXT_OPTIQMDG_API ThisThread
                {
                public:
                    /// Sets the processor affinity mask for the current thread.
                    static void affinity(const ThreadAffinity&);
                    static void affinity(CpuIndex);
                };
            }
        }
    }
}