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 <OnixS/CME/ConflatedTCP/ABI.h>
#include <OnixS/CME/ConflatedTCP/Messaging.h>
#include <OnixS/CME/ConflatedTCP/ThreadingModel.h>

#include <climits>
#include <set>
#include <string>
#include <vector>

namespace OnixS {
namespace CME {
namespace ConflatedTCP {

/**
 * Session settings.
 */
class SessionSettings
{
public:
    ONIXS_CONFLATEDTCP_EXPORTED
    SessionSettings();

    /// \return the session id that was assigned by the exchange.
    ///
    /// The default value is empty.
    ONIXS_CONFLATEDTCP_NODISCARD
    const std::string & sessionId() const {
        return sessionId_;
    }

    /// Sets the session id that was assigned by the exchange.
    ONIXS_CONFLATEDTCP_EXPORTED
    SessionSettings& sessionId(const std::string & value);

    /// \return the firm id that was assigned by the exchange.
    ///
    /// The default value is empty.
    ONIXS_CONFLATEDTCP_NODISCARD
    const std::string & firmId() const {
        return firmId_;
    }

    /// Sets the firm id that was assigned by the exchange.
    ONIXS_CONFLATEDTCP_EXPORTED
    SessionSettings& firmId(const std::string & value);

    /// \return the access key that was assigned by the exchange.
    ///
    /// The default value is empty.
    ONIXS_CONFLATEDTCP_NODISCARD
    const std::string & accessKey() const {
        return accessKey_;
    }

    /// Sets the access key that was assigned by the exchange.
    ONIXS_CONFLATEDTCP_EXPORTED
    SessionSettings& accessKey(const std::string & value);

    /// \return the secret key that was assigned by the exchange.
    ///
    /// The default value is empty.
    ONIXS_CONFLATEDTCP_NODISCARD
    const std::string & secretKey() const {
        return secretKey_;
    }

    /// Sets the secret key that was assigned by the exchange.
    ONIXS_CONFLATEDTCP_EXPORTED
    SessionSettings& secretKey(const std::string & value);

    /// \return the threading model.
    ///
    /// The defaul value is Default::ThreadingModelValue.
    ONIXS_CONFLATEDTCP_NODISCARD
    ThreadingModel::Enum threadingModel() const {
        return threadingModel_;
    }

    /// Sets the threading model.
    ONIXS_CONFLATEDTCP_EXPORTED
    SessionSettings& threadingModel(ThreadingModel::Enum value);

    /// The maximum spinning timeout (microseconds).
    static const unsigned MaxSpinningTimeoutUsec = 1000000; //1 sec

    /// \return the receive spinning timeout (microseconds).
    ///
    /// The defaul value is Default::ReceiveSpinningTimeout.
    ONIXS_CONFLATEDTCP_NODISCARD
    unsigned receiveSpinningTimeout() const {
        return receiveSpinningTimeout_;
    }

    /// Sets the receive spinning timeout (microseconds).
    ONIXS_CONFLATEDTCP_EXPORTED
    SessionSettings& receiveSpinningTimeout(unsigned usecTimeout);

    /// \return the send spinning timeout (microseconds).
    ///
    /// The defaul value is Default::SendSpinningTimeout.
    ONIXS_CONFLATEDTCP_NODISCARD
    unsigned sendSpinningTimeout() const
    {
        return sendSpinningTimeout_;
    }

    /// Sets the send spinning timeout (microseconds).
    ONIXS_CONFLATEDTCP_EXPORTED
    SessionSettings& sendSpinningTimeout(unsigned usecTimeout);

    /// \return the message grouping mode.
    ///
    /// - `0` means default grouping  - the messages are sent immediately, and pending messages (if any) are grouped till reaching of TCP buffer size.
    /// - `1` means the messages are sent immediately and never grouped.
    /// - `2` (or higher) means the messages are sent immediately, and pending messages are grouped by 2 (or higher).
    ///
    /// The defaul value is Default::MessageGrouping.
    ONIXS_CONFLATEDTCP_NODISCARD
    unsigned messageGrouping() const {
        return messageGrouping_;
    }

    /// Sets the message grouping mode.
    ONIXS_CONFLATEDTCP_EXPORTED
    SessionSettings& messageGrouping(unsigned value);

    /// Resets the settings to the default values.
    SessionSettings& resetToDefaults();

    /// Adds the path to the folder that contains license file(s).
    ONIXS_CONFLATEDTCP_EXPORTED
    SessionSettings& addLicenseStore(const std::string& value);

    /// Sets the path to the folder that contains license file(s).
    ONIXS_CONFLATEDTCP_EXPORTED
    SessionSettings& licenseStore(const std::string & value);

    /// Folders that contain license file(s).
    typedef std::vector<std::string> LicenseStores;

    /// \return path(s) to the folder that contains license file(s).
    ///
    /// The default value is '.'.
    ONIXS_CONFLATEDTCP_NODISCARD
    const LicenseStores& licenseStores() const
    {
        return licenseStores_;
    }

    /// \return the number of days to alert before the license expiration.
    ///
    /// The defaul value is Default::LicenseAlertingDaysBeforeExpiration.
    ONIXS_CONFLATEDTCP_NODISCARD
    unsigned licenseAlertingDaysBeforeExpiration() const {
        return licenseAlertingDaysBeforeExpiration_;
    }

    /// Sets the number of days to alert before the license expiration.
    ///
    /// If the amount of remaining license days is less or equal to this number,
    /// then the warning is reported to the Handler's log.
    ///
    /// The verification is performed during the Session::connect call.
    ONIXS_CONFLATEDTCP_EXPORTED
    SessionSettings& licenseAlertingDaysBeforeExpiration(unsigned days) {
        licenseAlertingDaysBeforeExpiration_ = days;
        return *this;
    }

    /// \return The interface name or IP-address from which the Handler connects to the counterparty.
    ///
    /// The default value is empty.
    ONIXS_CONFLATEDTCP_EXPORTED ONIXS_CONFLATEDTCP_NODISCARD
    const std::string & localNetworkInterface() const {
        return localNetworkInterface_;
    }

    /// Specifies the local interface from which the Handler connects to the counterparty.
    ///
    /// Each local interface specification could specify the local IP address and port.
    /// For instance, `localhost` and `192.168.0.1:4501` are valid values.
    ONIXS_CONFLATEDTCP_EXPORTED
    SessionSettings& localNetworkInterface(const std::string & value);

    /// \return the Handler log file name.
    ///
    /// The default value is `HandlerLog.txt`.
    ONIXS_CONFLATEDTCP_NODISCARD
    const std::string & logFileName() const {
        return logFileName_;
    }

    /// Specifies the Handler log file name.
    ONIXS_CONFLATEDTCP_EXPORTED
    SessionSettings& logFileName(const std::string & value);

    /// \return the Session Storage directory.
    ///
    /// Inbound and outbound messages, session's state data and the Handler log file are stored in this directory.
    ///
    /// The default value is `MsgStorage`.
    ONIXS_CONFLATEDTCP_NODISCARD
    const std::string & storageDirectory() const {
        return storageDirectory_;
    }

    /// Sets the Session Storage directory.
    ///
    /// Inbound and outbound messages, session's state data and the Handler log file are stored in this directory.
    ONIXS_CONFLATEDTCP_EXPORTED
    SessionSettings& storageDirectory(const std::string & value);

    /// \return the usage of the local time in Handler events and log files.
    ///
    /// The defaul value is Default::LocalTimeUsage.
    ONIXS_CONFLATEDTCP_NODISCARD
    bool localTimeUsage() const {
        return localTimeUsage_;
    }

    /// Specifies the usage of the local time in Handler events and log files.
    ///
    /// If it is `true`, then the local time is used, otherwise - UTC.
    ONIXS_CONFLATEDTCP_EXPORTED
    SessionSettings& localTimeUsage(bool);

    /// \return the segment size for the file-based session storage.
    ///
    /// The defaul value is Default::FileBasedStorageSegmentSize.
    ONIXS_CONFLATEDTCP_NODISCARD
    Messaging::UInt64 fileBasedStorageSegmentSize() const {
        return fileBasedStorageSegmentSize_;
    }

    /// Sets the segment size for file-based session storage.
    ONIXS_CONFLATEDTCP_EXPORTED
    SessionSettings& fileBasedStorageSegmentSize(Messaging::UInt64 value);

    /// \return the maximum size of the asynchronous session storage queue.
    ///
    /// By default, the size is unlimited.
    ONIXS_CONFLATEDTCP_NODISCARD
    unsigned asyncFileBasedStorageQueueMaxSize() const {
        return asyncFileBasedStorageQueueMaxSize_;
    }

    /// Sets the maximum size of the asynchronous session storage queue.
    ONIXS_CONFLATEDTCP_EXPORTED
    SessionSettings& asyncFileBasedStorageQueueMaxSize(unsigned value);

    /// \return the CPU index(es) for affinity of the asynchronous session storage threads.
    ///
    /// By default, the affinity is not set.
    ONIXS_CONFLATEDTCP_NODISCARD
    const CpuIndexes & asyncFileBasedStorageThreadAffinity() const {
        return asyncFileBasedStorageThreadAffinity_;
    }

    /// Specifies the CPU index(es) for affinity of the asynchronous session storage threads.
    ONIXS_CONFLATEDTCP_EXPORTED
    SessionSettings& asyncFileBasedStorageThreadAffinity(const CpuIndexes & cpuIndexes);

    /// \return The file-based storage integrity errors checking mode:
    ///
    /// - `true` - ignore errors and create a new storage
    /// - `false` - throw an exception
    ///
    /// The defaul value is Default::IgnoreFileBasedStorageIntegrityErrors.
    ONIXS_CONFLATEDTCP_NODISCARD
    bool ignoreFileBasedStorageIntegrityErrors() const {
        return ignoreFileBasedStorageIntegrityErrors_;
    }

    /// Sets the file-based storage integrity errors checking mode.
    ONIXS_CONFLATEDTCP_EXPORTED
    SessionSettings& ignoreFileBasedStorageIntegrityErrors(bool);

    /// \return `true` if outbound messages are logged before sending, 'false' otherwise.
    ///
    /// The defaul value is Default::LogBeforeSending.
    ONIXS_CONFLATEDTCP_NODISCARD
    bool logBeforeSending() const {
        return logBeforeSending_;
    }

    /// Controls the order of logging and sending outbound messages.
    ///
    /// \param before if 'true' then outbound messages are logged before sending.
    ONIXS_CONFLATEDTCP_EXPORTED
    SessionSettings& logBeforeSending(bool before);

    /// \return the maximum number of tries to restore the telecommunications link.
    ///
    /// The defaul value is Default::ReconnectAttempts.
    ONIXS_CONFLATEDTCP_NODISCARD
    unsigned reconnectAttempts() const {
        return reconnectAttempts_;
    }

    /// Sets the maximum number of tries to restore the telecommunications link.
    ONIXS_CONFLATEDTCP_EXPORTED
    SessionSettings& reconnectAttempts(unsigned reconnectAttempts);

    /// \return the time interval between retries to restore the telecommunications link (seconds).
    ///
    /// The defaul value is Default::ReconnectInterval.
    ONIXS_CONFLATEDTCP_NODISCARD
    unsigned reconnectInterval() const {
        return reconnectInterval_;
    }

    /// Sets the time interval between retries to restore the telecommunications link (seconds).
    ONIXS_CONFLATEDTCP_EXPORTED
    SessionSettings& reconnectInterval(unsigned value);

    /// Specifies the usage of the operating system default socket buffer size.
    static const int UseOsDefaultSocketBufferSize = -1;

    /// \return the socket receive buffer size.
    ///
    /// The default value is Default::SocketReceiveBufferSize.
    ONIXS_CONFLATEDTCP_NODISCARD
    int socketReceiveBufferSize() const {
        return socketReceiveBufferSize_;
    }

    /// Sets the socket receive buffer size.
    ///
    /// \param bufferSize the size of the socket receive buffer size.
    /// If SessionSettings::UseOsDefaultSocketBufferSize then the default operating system value is used.
    ONIXS_CONFLATEDTCP_EXPORTED
    SessionSettings& socketReceiveBufferSize(int bufferSize);

    /// \return the reasonable transmission time - as the percentage from the `KeepAliveInterval` value.
    ///
    /// The defaul value is Default::ReasonableTransmissionTime.
    ONIXS_CONFLATEDTCP_NODISCARD
    unsigned reasonableTransmissionTime() const {
        return reasonableTransmissionTime_;
    }

    /// Sets the reasonable transmission time - as the percentage from the `KeepAliveInterval` value.
    ONIXS_CONFLATEDTCP_EXPORTED
    SessionSettings& reasonableTransmissionTime(unsigned percentage);

    /// \return the size of the socket send buffer size.
    ///
    /// The default value is Default::SocketSedndBufferSize.
    ONIXS_CONFLATEDTCP_NODISCARD
    int socketSendBufferSize() const {
        return socketSendBufferSize_;
    }

    /// Sets the size of the socket send buffer size.
    ///
    /// \param bufferSize the size of the socket send buffer size.
    /// If SessionSettings::UseOsDefaultSocketBufferSize then the default operating system value is used.
    ONIXS_CONFLATEDTCP_EXPORTED
    SessionSettings& socketSendBufferSize(int bufferSize);

    /// \return the thread pool affinity.
    ONIXS_CONFLATEDTCP_NODISCARD
    const CpuIndexes & threadPoolAffinity() const {
        return threadPoolAffinity_;
    }

    /// Sets the thread pool affinity.
    ONIXS_CONFLATEDTCP_EXPORTED
    SessionSettings& threadPoolAffinity(const CpuIndexes & cpuIndexes);

    /// \return the thread pool priority.
    ONIXS_CONFLATEDTCP_NODISCARD
    int threadPoolPriority() const {
        return threadPoolPriority_;
    }

    /// Sets the thread pool priority.
    ONIXS_CONFLATEDTCP_EXPORTED
    SessionSettings& threadPoolPriority(int priority);

    /// \return the thread pool policy.
    ONIXS_CONFLATEDTCP_NODISCARD
    int threadPoolPolicy() const {
        return threadPoolPolicy_;
    }

    /// Sets the thread pool policy.
    ONIXS_CONFLATEDTCP_EXPORTED
    SessionSettings& threadPoolPolicy(int policy);

    /// \return the value of the option to improve latency at the expense of message throughput (the `TCP_NODELAY` socket option).
    ///
    /// The default value is Default::TcpNoDelayOption.
    ONIXS_CONFLATEDTCP_NODISCARD
    bool tcpNoDelayOption() const {
        return tcpNoDelayOption_;
    }

    /// Sets the value of the option to improve latency at the expense of message throughput (the `TCP_NODELAY` socket option).
    ONIXS_CONFLATEDTCP_EXPORTED
    SessionSettings& tcpNoDelayOption(bool value);

    /// \return the size of the shared thread pool.
    ///
    /// The default value is Default::ThreadPoolSize.
    ONIXS_CONFLATEDTCP_NODISCARD
    unsigned threadPoolSize() const {
        return threadPoolSize_;
    }

    /// Sets the size of the shared thread pool.
    ONIXS_CONFLATEDTCP_EXPORTED
    SessionSettings& threadPoolSize(unsigned numberOfThreads);

    /// \return the longest time in milliseconds the client system can remain silent before sending a message.
    ///
    /// The default value is Default::KeepAliveInterval.
    ONIXS_CONFLATEDTCP_EXPORTED ONIXS_CONFLATEDTCP_NODISCARD
    unsigned keepAliveInterval() const
    {
        return keepAliveInterval_;
    }

    /// Sets the longest time in milliseconds the client system can remain silent before sending
    /// a message.
    ///
    /// \note Allowed range is between `5000` - `60000`. Any value outside this range will be rejected.
    ONIXS_CONFLATEDTCP_EXPORTED
    SessionSettings& keepAliveInterval(unsigned milliseconds);

    /// Loads the settings from the given configuration file.
    ///
    /// \see Key
    ONIXS_CONFLATEDTCP_EXPORTED
    SessionSettings& load(const std::string& configFile);

    /// \return the human-friendly description.
    ONIXS_CONFLATEDTCP_EXPORTED ONIXS_CONFLATEDTCP_NODISCARD
    std::string toString() const;

    /// Default session settings.
    struct ONIXS_CONFLATEDTCP_EXPORTED Default {
        static const ThreadingModel::Enum ThreadingModelValue = ThreadingModel::DedicatedThreads;
        static const bool CreateLogFile = true;
        static const int KeepAliveInterval = 30000;
        static const bool LogBeforeSending = true;
        static const int SocketSendBufferSize = UseOsDefaultSocketBufferSize;
        static const int SocketReceiveBufferSize = UseOsDefaultSocketBufferSize;
        static const bool TcpNoDelayOption = true;
        static const int ReceiveSpinningTimeout = 0;
        static const int SendSpinningTimeout = 0;
        static const char LicenseStore[] ;
        static const unsigned LicenseAlertingDaysBeforeExpiration = 0;
        static const char LogDir[];
        static const char LogFileName[];
        static const bool LocalTimeUsage = false;
        static const unsigned MessageGrouping = 0;
        static const int ReasonableTransmissionTime = 20;
        static const int ReconnectAttempts = 3;
        static const int ReconnectInterval = 180;
        static const unsigned long long FileBasedStorageSegmentSize = 0;
        static const bool IgnoreFileBasedStorageIntegrityErrors = false;
        static const int ThreadPoolSize = 0;
        static const unsigned AsyncFileBasedStorageQueueMaxSize = UINT_MAX;
    };

    /// The keys that are used to load settings from the configuration file.
    struct ONIXS_CONFLATEDTCP_EXPORTED Key {
        static const char * SessionId;                                      ///< = "SessionId"
        static const char * FirmId;                                         ///< = "FirmId"
        static const char * AccessKey;                                      ///< = "AccessKey"
        static const char * SecretKey;                                      ///< = "SecretKey"

        static const char * AsyncFileBasedStorageQueueMaxSize;              ///< = "AsyncFileBasedStorage.QueueMaxSize"
        static const char * AsyncFileBasedStorageThreadAffinity;            ///< = "AsyncFileBasedStorage.ThreadAffinity"
        static const char * ThreadingModel;                                 ///< = "ThreadingModel"
        static const char * TcpNoDelayOption;                               ///< = "TcpNoDelayOption"
        static const char * MessageGrouping;                                ///< = "MessageGrouping"
        static const char * FileBasedStorageSegmentSize;                    ///< = "FileBasedStorageSegmentSize"
        static const char * IgnoreFileBasedStorageIntegrityErrors;          ///< = "IgnoreFileBasedStorageIntegrityErrors"
        static const char * KeepAliveInterval;                              ///< = "KeepAliveInterval"
        static const char * LicenseFile;                                    ///< = "LicenseFile"
        static const char * LicenseStore;                                   ///< = "LicenseStore"
        static const char * LicenseAlertingDaysBeforeExpiration;            ///< = "LicenseAlertingDaysBeforeExpiration"
        static const char * LocalNetworkInterface;                          ///< = "LocalNetworkInterface"
        static const char * LogFileName;                                    ///< = "Log.FileName"
        static const char * LocalTimeUsage;                                 ///< = "LocalTimeUsage"
        static const char * LogBeforeSending;                               ///< = "Log.BeforeSending"
        static const char * ReasonableTransmissionTime;                     ///< = "ReasonableTransmissionTime"
        static const char * ReceiveSpinningTimeout;                         ///< = "ReceiveSpinningTimeout"
        static const char * ReconnectAttempts;                              ///< = "Reconnect.Attempts"
        static const char * ReconnectInterval;                              ///< = "Reconnect.Interval"
        static const char * SendSpinningTimeout;                            ///< = "SendSpinningTimeout"
        static const char * ThreadPoolAffinity;                             ///< = "ThreadPool.Affinity"
        static const char * ThreadPoolSize;                                 ///< = "ThreadPool.Size"
        static const char * ThreadPoolPriority;                             ///< = "ThreadPool.Priority"
        static const char * ThreadPoolPolicy;                               ///< = "ThreadPool.Policy"
        static const char * SocketReceiveBufferSize;                        ///< = "Socket.ReceiveBufferSize"
        static const char * SocketSendBufferSize;                           ///< = "Socket.SendBufferSize"
        static const char * StorageDirectory;                               ///< = "Log.Directory"
    };

private:
    void processLicenseStores(const std::string& licenseStore);

    std::string accessKey_;

    unsigned asyncFileBasedStorageQueueMaxSize_;

    CpuIndexes asyncFileBasedStorageThreadAffinity_;

    bool createEngineLogFile_;

    Messaging::UInt64 fileBasedStorageSegmentSize_;

    std::string firmId_;

    bool ignoreFileBasedStorageIntegrityErrors_;

    unsigned keepAliveInterval_;

    unsigned licenseAlertingDaysBeforeExpiration_;

    std::string licenseFilePath_;

    LicenseStores licenseStores_;

    std::string localNetworkInterface_;

    bool localTimeUsage_;

    bool logBeforeSending_;

    std::string logFileName_;

    unsigned messageGrouping_;

    unsigned reasonableTransmissionTime_;

    int receiveSpinningTimeout_;

    unsigned reconnectAttempts_;

    unsigned reconnectInterval_;

    std::string secretKey_;

    int sendSpinningTimeout_;

    std::string sessionId_;

    int socketReceiveBufferSize_;

    int socketSendBufferSize_;

    std::string storageDirectory_;

    bool tcpNoDelayOption_;

    ThreadingModel::Enum threadingModel_;

    CpuIndexes threadPoolAffinity_;

    int threadPoolPolicy_;

    int threadPoolPriority_;

    unsigned threadPoolSize_;
};

}
}
}