SessionScheduler.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 <set>

#include <OnixS/FIXEngine/ABI.h>

#include <OnixS/FIXEngine/Threading/Thread.h>

namespace OnixS {
namespace FIX {
ONIXS_FIXENGINE_API_DECL(class, Session);

namespace Scheduling {
ONIXS_FIXENGINE_API_DECL(class, SessionScheduler);

ONIXS_FIXENGINE_API_DECL(class, SessionSchedule);
ONIXS_FIXENGINE_API_DECL(class, SessionConnectionSettings);
ONIXS_FIXENGINE_API_DECL(class, Counterparty);

typedef std::string SessionScheduleId;
typedef std::string SessionConnectionSettingsId;

/// SessionScheduler events notifications.
class
    ONIXS_FIXENGINE_API
    SessionSchedulerListener
{
public:
    /// Notifies if the FIX session is about to be closed.
    /// @param scheduler Identifies an instance of the session
    /// scheduler which is about to close the scheduled session.
    /// @param session Identifies the session which is about to be closed.
    /// @param allowLogout Defines whether the session
    /// scheduler must perform the logout. To prohibit
    /// the session logout it's necessary to set it to 'false'.
    virtual
    void
    onLoggingOut(
        const SessionScheduler & scheduler,
        Session * session,
        bool * allowLogout) = 0;

    /// Allows scheduler's users to be notified when an initiator will try
    /// to connect to the next counterparty.
    /// The parameter `Counterparty` provides a counterparty,
    /// to which the session will connect.
    virtual
    void
    onInitiatorConnecting(
        const SessionScheduler &,
        Session *,
        const Counterparty &) {}

    /// Notifies about a non-critical issue occurred
    /// while maintaining the state for the given session.
    virtual
    void
    onWarning(
        const SessionScheduler & scheduler,
        Session * session,
        const std::string & warningReason) = 0;

    /// Notifies about an error occurred while
    /// maintaining the state for the given session.
    virtual
    void
    onError(
        const SessionScheduler & scheduler,
        Session * session,
        const std::string & errorReason) = 0;

protected:
    /// The class is not used for the object life time managing.
    /// Therefore, destructor is in the protected area.
    virtual ~SessionSchedulerListener() ONIXS_FIXENGINE_DEFAULT;
};

/// The way in which the Scheduler will utilize threads.
struct SchedulerThreadingModel
{
    enum Enum
    {
        /// Scheduler will use its own threads.
        DedicatedThreads,

        /// Scheduler events are handled by rolling an event loop in a user thread.
        ExternalThread
    };

    /// Returns the textual representation of the SchedulerThreadingModel::Enum value.
    ONIXS_FIXENGINE_API static const char * toString(SchedulerThreadingModel::Enum value);
};

/// The collection of miscellaneous parameters
/// which affect the session scheduler behavior.
class
    ONIXS_FIXENGINE_API
    SessionSchedulerOptions
{
public:
    /// Initializes parameters with default values.
    SessionSchedulerOptions();

    /// Cleans everything up.
    ~SessionSchedulerOptions();

    /// The path to the scheduler configuration file.
    const std::string & configurationFile() const;

    /// Updates the path to the scheduler configuration file.
    void configurationFile(const std::string & file);

    /// An instance of the event listener to notify about events.
    SessionSchedulerListener * eventListener() const;

    /// Associates the given event listener with the scheduler.
    void eventListener(SessionSchedulerListener * listener);

    /// The threading model.
    SchedulerThreadingModel::Enum threadingModel() const;

    /// Updates the threading model.
    void threadingModel(SchedulerThreadingModel::Enum threadingModel);

private:
    std::string * configurationFile_;
    SessionSchedulerListener * eventListener_;
    SchedulerThreadingModel::Enum threadingModel_;
};

/// The scheduler performs the session connection maintenance according
/// to the specified schedule for session activities. It monitors
/// whenever criteria to log a particular session, either on or off,
/// is triggered and automatically executes an appropriate action.
class ONIXS_FIXENGINE_API SessionScheduler
{
public:
    /// Initializes the Scheduler instance according to the options
    /// specified in the given configuration file.
    ///
    /// If specified, the Scheduler extracts from the configuration a set
    /// of predefined session schedules and connection settings later
    /// available through Schedules and ConnectionSettings properties.
    SessionScheduler(
        const SessionSchedulerOptions & options);

    /// Performs the graceful shutdown of scheduling services.
    ~SessionScheduler();

    /// Looks for the predefined session schedule
    /// associated with the given unique names (ids) as it
    /// was specified in the Scheduler's configuration file.
    /// @return NULL if no a schedule available under the given id.
    const
    SessionSchedule *
    findSchedule(const SessionScheduleId & id) const;

    /// Looks for the predefined session connection settings
    /// associated with the given unique names (ids) as it was
    /// specified in the Scheduler's configuration file.
    /// @return NULL if no settings available under the given id.
    const
    SessionConnectionSettings *
    findConnectionSettings(
        const SessionConnectionSettingsId & id) const;

    /// Adds the session to the automatic connection management.
    ///
    /// If the session is added during an active time frame,
    /// it will be connected immediately. If the session is
    /// registered during an inactive time frame and has an active state,
    /// it will be disconnected. If the session is already registered,
    /// an exception will be thrown.
    ///
    /// @param session An instance of the session to be maintained.
    /// @param schedule The schedule which defines the session connection
    /// time, periodicity as well as other attributes.
    /// @param connection Settings for the given session to
    /// be used when the session must be connected.
    void
    add(
        Session * session,
        const SessionSchedule & schedule,
        const SessionConnectionSettings & connection);

    /// Adds the session to the automatic connection management.
    ///
    /// If the session is added during an active time frame,
    /// it will be connected immediately. If the session is
    /// registered during an inactive time frame and has an active state,
    /// it will be disconnected. If the session is already registered,
    /// an exception will be thrown.
    ///
    /// @param session An instance of the session to be maintained.
    /// @param scheduleId The id of the predefined schedule
    /// to use for the given session.
    /// @param connectionId The id of the predefined connection
    /// settings to use for the given session.
    void
    add(
        Session * session,
        const SessionScheduleId & scheduleId,
        const SessionConnectionSettingsId & connectionId);

    /// Removes the session from the automatic connection management services.
    /// If the session were not registered before, it does actually nothing.
    void remove(Session * session);

    /// Processes events on the Scheduler and performs the necessary session management.
    ///
    /// This method should be called periodically and only when the ExternalThread threading model is used.
    /// This method is not thread-safe.
    void dispatchEvents();

    /**
    * Sets the CPU affinity of the Scheduler service thread.
    */
    void serviceThreadAffinity(const OnixS::Threading::CpuIndexes & cpuIndexes);

    /**
    * Returns the CPU affinity of the Scheduler service thread.
    */
    const OnixS::Threading::CpuIndexes & serviceThreadAffinity() const;

    /**
    * Sets the number of logon attempts in case of a logon failure.
    */
    void reconnectAttempts(int value);

    /**
    * Returns the number of logon attempts in case of a logon failure.
    * By default, the option value is equal to 3.
    */
    int reconnectAttempts() const;

    /**
    * Sets the time interval between logon attempts in case of a logon failure. (in seconds).
    */
    void reconnectInterval(int value);

    /**
    * Returns the time interval between logon attempts in case of a logon failure. (in seconds).
    * By default, the option value is equal to 180 seconds.
    */
    int reconnectInterval() const;

    /**
    * This property allows switching the local time to the UTC time usage.
    */
    void utcTimeUsage(bool value);

    /**
    * Returns true if the UTC time is used otherwise false.
    * By default, the option value is false.
    */
    bool utcTimeUsage() const;

private:
    class Impl;
    Impl * impl_;
};
}
}
}