Pluggable Session Storage

Pluggable session storage is the storage implemented by the user.

For example, it could be used to implement High-Availability (HA) Solutions:

One can implement a Pluggable Session Storage that stores data to shared storage. If one server fails and another reserve server activates, the Handler can restore session states from the shared storage.

Such storage should implement the OnixS::CME::ConflatedTCP::SessionStorage interface.

Implementing Pluggable Storage

There are a few basic rules that should be applied to the implementation of Pluggable Storage.

• The user should manage the lifecycle of the storage. The Handler treats the instance of a Pluggable Storage as a "foreign" object and never attempts to delete it. On the other hand, there is a strong requirement to keep storage instance valid until the OnixS::CME::ConflatedTCP::Session instance is destroyed.
• Be as fast as possible. The Pluggable Storage is a part of the message send/receive path, so it has a direct effect on the sending/receiving latency and overall throughput of the system.
• Avoid throwing exceptions. Exceptions thrown from Pluggable Storage callbacks immediately break a session.
• Don't make assumptions about the parameters' lifecycle. Whenever you need to keep such data for separate usage, you should make copies of messages or memory blocks and store them in an appropriate place, but don't keep raw pointers, passed to callbacks.
• No synchronization is required. The Handler manages all synchronization issues, so all methods of Pluggable Storage are called sequentially.
• Track message numbers when the message is logged. Message sequence numbers should be tracked while messages are logged, i.e. during OnixS::CME::ConflatedTCP::SessionStorage::storeInboundMessage or OnixS::CME::ConflatedTCP::SessionStorage::storeOutboundMessage methods. These numbers should be kept and returned to the Handler through OnixS::CME::ConflatedTCP::SessionStorage::inSeqNum() and OnixS::CME::ConflatedTCP::SessionStorage::outSeqNum() calls.

Call Order of Pluggable Storage Methods

This section explains how different methods of Pluggable Storage are called in different situations.

Incoming message handling

• When there is a session-level message, the following methods are called:
  • OnixS::CME::ConflatedTCP::SessionStorage::storeInboundMessage
  • OnixS::CME::ConflatedTCP::SessionListener methods, if the listener is present
• When there is an application-level message, the call order is reversed:
  • OnixS::CME::ConflatedTCP::SessionListener methods, if the listener is present
  • OnixS::CME::ConflatedTCP::SessionStorage::storeInboundMessage.

If the user's code throws an exception on any stage, the session becomes disconnected, and subsequent steps are omitted.

Outgoing message handling

• OnixS::CME::ConflatedTCP::SessionListener methods.
• OnixS::CME::ConflatedTCP::SessionStorage::storeOutboundMessage.

Example

class MySessionStorage : public SessionStorage
{
public:
    const std::string& id() const ONIXS_CONFLATEDTCP_OVERRIDE;

    UInt64 uuid() const ONIXS_CONFLATEDTCP_OVERRIDE;

    void uuid(UInt64 value) ONIXS_CONFLATEDTCP_OVERRIDE;

    UInt64 previousUuid() const ONIXS_CONFLATEDTCP_OVERRIDE;

    void previousUuid(UInt64 value) ONIXS_CONFLATEDTCP_OVERRIDE;

    SeqNumber inSeqNum() const ONIXS_CONFLATEDTCP_OVERRIDE;

    void inSeqNum(SeqNumber msgSeqNum) ONIXS_CONFLATEDTCP_OVERRIDE;

    SeqNumber previousSeqNum() const ONIXS_CONFLATEDTCP_OVERRIDE;

    void previousSeqNum(SeqNumber msgSeqNum) ONIXS_CONFLATEDTCP_OVERRIDE;

    SeqNumber outSeqNum() const ONIXS_CONFLATEDTCP_OVERRIDE;

    void outSeqNum(SeqNumber msgSeqNum) ONIXS_CONFLATEDTCP_OVERRIDE;

    bool terminated() const ONIXS_CONFLATEDTCP_OVERRIDE;

    void terminated(bool status) ONIXS_CONFLATEDTCP_OVERRIDE;

    Timestamp sessionCreationTime() const ONIXS_CONFLATEDTCP_OVERRIDE;

    void sessionCreationTime(Timestamp) ONIXS_CONFLATEDTCP_OVERRIDE;

    void clear() ONIXS_CONFLATEDTCP_OVERRIDE;

    void close(bool terminate = false, bool doBackup = false) ONIXS_CONFLATEDTCP_OVERRIDE;

    void storeInboundMessage(const RawMessagePointer& rawMsg, SeqNumber msgSeqNum, bool isOriginal, Timestamp messageReceivingUtcTimestamp = Timestamp()) ONIXS_CONFLATEDTCP_OVERRIDE;

    void storeOutboundMessage(const RawMessagePointer& rawMsg, SeqNumber msgSeqNum, bool isOriginal = true, bool warmUp = false, Timestamp messageSendingUtcTimestamp = Timestamp()) ONIXS_CONFLATEDTCP_OVERRIDE;

    void flush() ONIXS_CONFLATEDTCP_OVERRIDE;
};
};

void pluggableStorage()
{
    SessionSettings sessionSettings;
    int MarketSegmentId = 0;

    MySessionStorage myStorage;

    Session session(sessionSettings, MarketSegmentId, ONIXS_CONFLATEDTCP_NULLPTR, ONIXS_CONFLATEDTCP_NULLPTR, SessionStorageType::Pluggable, &myStorage);
}

See also

the "PluggableStorage" sample from the distribution package.