SolarflareFeedEngine.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/CME/MDH/Watch.h>
#include <OnixS/CME/MDH/PacketTraits.h>
#include <OnixS/CME/MDH/FeedEngine.h>

ONIXS_CMEMDH_NAMESPACE_BEGIN

/// Defines modes in with the Solarflare Feed Engine can operate.
struct ONIXS_CMEMDH_LTWT SolarflareFeedEngineOperatingMode
{
    /// Underlying integral type for the enum.
    typedef UInt32 Base;

    /// Defines modes in with the Solarflare Feed Engine can operate.
    enum Enum
    {
        /// The conventional mode supposes use of the ef_vi
        /// services only while working with multicast feeds.
        ///
        /// Thus attempt to establish multicast data reception
        /// on non-Solarflare network interfaces while using the
        /// Solarflare Feed Engine will lead to a failure.
        Conventional,

        /// In the given mode the Solarflare Feed Engine mixes
        /// ef_vi services with the traditional network sockets.
        ///
        /// The Solarflare Feed Engine uses ordinary network
        /// sockets to receive multicast data on the non-Solarflare
        /// network interfaces instead of giving up on operating.
        /// The given mode offers more flexibility for the cases
        /// when the operating environment is configured in such
        /// a way that real-time incremental data arrives via a
        /// Solarflare network interface, while recovery data via
        /// a non-Solarflare network interface.
        Mixed
    };
};

/// Serializes the Solarflare Feed Engine
/// operational mode into a string.
ONIXS_CMEMDH_EXPORTED
void toStr(std::string&, SolarflareFeedEngineOperatingMode::Enum);

/// Serializes the Solarflare Feed Engine
/// operational mode into a string.
inline std::string toStr(SolarflareFeedEngineOperatingMode::Enum mode)
{
    std::string str;

    toStr(str, mode);

    return str;
}

/// Represents a collection of settings affecting
/// the behavior of the Feed Engine while working
/// with virtual interfaces.
class ONIXS_CMEMDH_LTWT SolarflareFeedEngineSettings
{
public:
    /// Initializes the given instance of the
    /// network settings with the default values.
    SolarflareFeedEngineSettings()
        : mode_(SolarflareFeedEngineOperatingMode::Conventional)
        , receiveRingSize_(static_cast<UInt32>(-1))
        , cacheSize_(1024)
        , socketBufferSize_(8 * 1024 * 1024)
        , watch_(&UtcWatch::service())
    {
    }

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

    /// The operational mode for the Feed Engine.
    SolarflareFeedEngineOperatingMode::Enum mode() const
    {
        return mode_;
    }

    /// Defines the operational mode for the Feed Engine.
    void mode(SolarflareFeedEngineOperatingMode::Enum mode)
    {
        mode_ = mode;
    }

    /// 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.
    ///
    /// By default, the parameter is set to '-1' which means
    /// receive ring will be constructed of the default capacity.
    UInt32 receiveRingSize() const
    {
        return 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.
    ///
    /// By default, the parameter is set to '-1' which means
    /// receive ring will be constructed of the default capacity.
    void receiveRingSize(UInt32 ringSize)
    {
        receiveRingSize_ = ringSize;
    }

    /// Size of a pool of buffers used to
    /// receive and manipulate incoming data.
    ///
    /// The Feed Engine puts incoming packets into buffers
    /// and keeps buffers busy until received data is processed
    /// by handlers. In case of rapid transmission, buffers may
    /// be allocated quicker than they are processed and released
    /// back to pool. Therefore, the pool must be capacious enough
    /// to avoid data losses.
    UInt32 cacheSize() const
    {
        return cacheSize_;
    }

    /// Size of pool of buffers used to
    /// receive and manipulate incoming data.
    void cacheSize(UInt32 cacheSize)
    {
        cacheSize_ = cacheSize;
    }

    /// Socket buffer size.
    ///
    /// When the Solarflare Feed Engine operates in mixed mode,
    /// ordinary sockets are used to receive multicast data on
    /// non-Solarflare network interfaces. The given parameter
    /// defines size of a buffer used by socket to store incoming
    /// data before it's retrieved by the Solarflare Feed Engine.
    UInt32 socketBufferSize() const
    {
        return socketBufferSize_;
    }

    /// Specifies socket buffer size.
    ///
    /// When the Solarflare Feed Engine operates in mixed mode,
    /// ordinary sockets are used to receive multicast data on
    /// non-Solarflare network interfaces. The given parameter
    /// defines size of a buffer used by socket to store incoming
    /// data before it's retrieved by the Solarflare Feed Engine.
    void socketBufferSize(UInt32 bufferSize)
    {
        socketBufferSize_ = bufferSize;
    }

    /// Watch service to be used by the Solarlfare Feed Engine.
    ///
    /// Watch is used by the Solarlfare Feed Engine to assign
    /// time stamps to incoming packets (received from feeds).
    ///
    /// @note By default, the TC watch service is used.
    WatchService& watch() const
    {
        return *watch_;
    }

    /// Watch service to be used by Feed Engine.
    ///
    /// If no instance is associated, the UTC watch is used.
    void watch(WatchService& watch)
    {
        watch_ = &watch;
    }

private:
    SolarflareFeedEngineOperatingMode::Enum mode_;

    UInt32 receiveRingSize_;
    UInt32 cacheSize_;

    UInt32 socketBufferSize_;

    WatchService* watch_;
};

/// Serializes the Solarflare Feed Engine settings into a string.
ONIXS_CMEMDH_EXPORTED
void toStr(std::string&, const SolarflareFeedEngineSettings&);

/// Serializes the Solarflare Feed Engine settings into a string.
inline std::string toStr(const SolarflareFeedEngineSettings& settings)
{
    std::string str;

    toStr(str, settings);

    return str;
}

/// The given class implements the Feed Engine
/// concept using the Solarlfare ef_vi SDK.
///
/// The ef_vi SDK is for high performance raw Ethernet
/// networking. It bypasses kernel and uses zero-copying
/// techniques while manipulating data.
class ONIXS_CMEMDH_EXPORTED SolarflareFeedEngine : public NetFeedEngine
{
public:
    /// Initializes the engine according to the given configuration.
    SolarflareFeedEngine(const SolarflareFeedEngineSettings&);

    /// Destructs the given instance.
    ~SolarflareFeedEngine() ONIXS_CMEMDH_OVERRIDE;

    /// Appends information on the given
    /// implementation to the given string.
    void info(std::string&) ONIXS_CMEMDH_OVERRIDE;

    /// Allocates a link for the given feed.
    NetFeedLink& allocate(const NetFeed&) ONIXS_CMEMDH_OVERRIDE;

    /// Exposes an instance of the watch service
    /// used while manipulating the feed links.
    WatchService& watch() ONIXS_CMEMDH_OVERRIDE;

    /// Carries out pending actions like
    /// data retrieval and event dispatching.
    NetFeedEngineProcessResult process() ONIXS_CMEMDH_OVERRIDE;

private:
    // The workhorse for the feed engine.
    class Workhorse;

    Workhorse* workhorse_;
};

ONIXS_CMEMDH_NAMESPACE_END