amps-python-client 5.3.4.1__zip → 5.3.4.2__zip

amps-python-client-5.3.4.1/src/cpp/include/amps/BookmarkStore.hpp

@@ -1,542 +0,0 @@
-////////////////////////////////////////////////////////////////////////////
-//
-// Copyright (c) 2010-2023 60East Technologies Inc., All Rights Reserved.
-//
-// This computer software is owned by 60East Technologies Inc. and is
-// protected by U.S. copyright laws and other laws and by international
-// treaties.  This computer software is furnished by 60East Technologies
-// Inc. pursuant to a written license agreement and may be used, copied,
-// transmitted, and stored only in accordance with the terms of such
-// license agreement and with the inclusion of the above copyright notice.
-// This computer software or any other copies thereof may not be provided
-// or otherwise made available to any other person.
-//
-// U.S. Government Restricted Rights.  This computer software: (a) was
-// developed at private expense and is in all respects the proprietary
-// information of 60East Technologies Inc.; (b) was not developed with
-// government funds; (c) is a trade secret of 60East Technologies Inc.
-// for all purposes of the Freedom of Information Act; and (d) is a
-// commercial item and thus, pursuant to Section 12.212 of the Federal
-// Acquisition Regulations (FAR) and DFAR Supplement Section 227.7202,
-// Government's use, duplication or disclosure of the computer software
-// is subject to the restrictions set forth by 60East Technologies Inc..
-//
-////////////////////////////////////////////////////////////////////////////
-#ifndef _BOOKMARKSTORE_H_
-#define _BOOKMARKSTORE_H_
-#include <string>
-#include "amps/Message.hpp"
-#include "amps/util.hpp"
-
-namespace AMPS
-{
-
-  /**
-   @defgroup specialBookmarks Special Bookmark Values
-
-   The AMPS C++ client includes definitions of special bookmark values. These
-   are used with AMPS::Client::bookmarkSubscribe() as values provided to the
-   bookmark parameter.
-
-   @{
-  */
-
-/// Start the subscription at the first undiscarded message in the bookmark
-/// store, or at the end of the bookmark store if all messages have been
-/// discarded.
-#define AMPS_BOOKMARK_RECENT "recent"
-
-///
-/// Start the subscription at the beginning of the journal.
-#define AMPS_BOOKMARK_EPOCH "0"
-
-///
-/// Start the subscription at the point in time when AMPS processes the subscription.
-#define AMPS_BOOKMARK_NOW "0|1|"
-
-  /* @}  */
-
-  class BookmarkStore;
-
-///
-/// Function type for BookmarkStore resize events
-/// The store_ param is store which is resizing.
-/// The subId_ param is the subscription id for which a resize is required.
-/// The size_ is the number of bytes being requested for the new size.
-/// The userData_ is the userData_ that was set when the handler was set on the store.
-/// The return value should be true if resize should proceed and false if the
-/// the size should be unchanged. A false value should only be returned if some
-/// other action was taken to free up space within the store.
-  typedef bool (*BookmarkStoreResizeHandler)(BookmarkStore store_,
-                                             const Message::Field& subId_,
-                                             size_t size_,
-                                             void* userData_);
-
-///
-/// Abstract base class for storing received bookmarks for HA clients.
-  class BookmarkStoreImpl : public RefBody
-  {
-  public:
-    BookmarkStoreImpl()
-      : _resizeHandler(NULL)
-      , _resizeHandlerData(NULL)
-      , _maxSubIdLength(AMPS_MAX_SUBID_LEN)
-    {;}
-
-    virtual ~BookmarkStoreImpl() {;}
-
-    ///
-    /// Log a bookmark to the persistent log.
-    /// \param message_ The Message to log in the store.
-    /// \return the corresponding bookmark sequence number
-    ///         for this bookmark
-    ///
-    virtual size_t log(Message& message_) = 0;
-
-    ///
-    /// Log a discard-bookmark entry to the persistent log
-    /// based on a bookmark sequence number.
-    /// \param subId_ The id of the subscription to which the bookmark applies.
-    /// \param bookmarkSeqNo_ The bookmark sequence number to discard.
-    ///
-    virtual void discard(const Message::Field& subId_,
-                         size_t bookmarkSeqNo_) = 0;
-
-    ///
-    /// Log a discard-bookmark entry to the persistent log
-    /// based on a bookmark sequence number.
-    /// \param message_ The Message to discard from the store.
-    ///
-    virtual void discard(const Message& message_) = 0;
-
-    ///
-    /// Returns the most recent bookmark from the log that
-    /// ought to be used for (re-)subscriptions.
-    /// \param subId_ The id of the subscription to check.
-    /// \return Most recent bookmark.
-    ///
-    virtual Message::Field getMostRecent(const Message::Field& subId_) = 0;
-
-    ///
-    /// Called for each arriving message to determine if
-    /// the application has already seen this bookmark and should
-    /// not be reprocessed.  Returns 'true' if the bookmark is
-    /// in the log and should not be re-processed, false otherwise.
-    /// \param message_ The Message to check.
-    /// \return Whether or not the bookmark has been discarded.
-    ///
-    virtual bool isDiscarded(Message& message_) = 0;
-
-    ///
-    /// Called to purge the contents of this store.
-    /// Removes any tracking history associated with publishers and received
-    /// messages, and may delete or truncate on-disk representations as well.
-    ///
-    virtual void purge() = 0;
-
-    ///
-    /// Called to purge the contents of this store for particular subId.
-    /// Removes any tracking history associated with publishers and received
-    /// messages, and will remove the subId from the file as well.
-    ///
-    virtual void purge(const Message::Field& subId_) = 0;
-
-    ///
-    /// Called to find the oldest bookmark sequence in the store.
-    /// \param subId_ The subscription ID on which to find the oldest bookmark.
-    /// \return The bookmark sequence that is oldest in the store for subId_
-    virtual size_t getOldestBookmarkSeq(const Message::Field& subId_) = 0;
-
-    ///
-    /// Set a handler on the bookmark store that will get called whenever
-    /// a resize of the store is required due to the number of stored
-    /// bookmarks exceeding the currently allocated storage to hold them.
-    /// \param handler_ The handler to be called when resizing.
-    /// \param userData_ User data passed to the handler when it is called.
-    virtual void setResizeHandler(BookmarkStoreResizeHandler handler_, void* userData_)
-    {
-      _resizeHandler = handler_;
-      _resizeHandlerData = userData_;
-    }
-
-    ///
-    /// Mark the bookmark provided as replicated to all sync replication
-    /// destinations for the given subscription.
-    /// \param subId_ The subscription Id to which the bookmark applies.
-    /// \param bookmark_ The most recent replicated bookmark.
-    virtual void persisted(const Message::Field& subId_,
-                           const Message::Field& bookmark_) = 0;
-
-    ///
-    /// Mark the bookmark provided as replicated to all sync replication
-    /// destinations for the given subscription.
-    /// \param subId_ The subscription Id to which the bookmark applies.
-    /// \param bookmark_ The most recent bookmark's sequence number.
-    /// \return The bookmark field that was just marked persisted.
-    virtual Message::Field persisted(const Message::Field& subId_, size_t bookmark_) = 0;
-
-    ///
-    /// Internally used to set the server version so the store knows how to deal
-    /// with persisted acks and calls to getMostRecent().
-    /// \param version_ The version of the server being used.
-    virtual void setServerVersion(size_t version_) = 0;
-
-    ///
-    /// Internally used to set the server version so the store knows how to deal
-    /// with persisted acks and calls to getMostRecent().
-    /// \param version_ The version of the server being used.
-    virtual void setServerVersion(const VersionInfo& version_) = 0;
-
-    bool callResizeHandler(const Message::Field& subId_, size_t newSize_);
-
-    inline void prune(const std::string& tmpFileName_ = std::string())
-    {
-      _prune(tmpFileName_);
-    }
-
-    virtual void _prune(const std::string&)
-    {
-      return;
-    }
-
-    ///
-    /// Gets the maximum allowed length for a sub id when recovering a bookmark
-    /// store from persistent storage.
-    /// \return The maximum length allowed.
-    size_t getMaxSubIdLength() const
-    {
-      return _maxSubIdLength;
-    }
-
-    ///
-    /// Sets the maximum allowed length for a sub id when recovering a bookmark
-    /// store from persistent storage.
-    /// \param maxSubIdLength_ The maximum length allowed.
-    void setMaxSubIdLength(size_t maxSubIdLength_)
-    {
-      _maxSubIdLength = maxSubIdLength_;
-    }
-
-  private:
-    BookmarkStoreResizeHandler  _resizeHandler;
-    void*                       _resizeHandlerData;
-    size_t                      _maxSubIdLength;
-  };
-
-///
-/// Interface for BookmarkStoreImpl classes.
-  class BookmarkStore
-  {
-    RefHandle<BookmarkStoreImpl> _body;
-  public:
-    ///
-    /// Creates a BookmarkStore that does nothing
-    BookmarkStore() {;}
-
-    ///
-    /// Creates a BookmarkStore based on the given implementation
-    BookmarkStore(BookmarkStoreImpl* impl_) : _body(impl_) {;}
-
-    BookmarkStore(const BookmarkStore& rhs) : _body(rhs._body) {;}
-
-    BookmarkStore& operator=(const BookmarkStore& rhs)
-    {
-      _body = rhs._body;
-      return *this;
-    }
-
-    ~BookmarkStore() {;}
-
-    ///
-    /// Sets the BookmarkStore to use the given implementation
-    void setImplementation(BookmarkStoreImpl* impl_)
-    {
-      _body = impl_;
-    }
-
-    bool isValid() const
-    {
-      return _body.isValid();
-    }
-
-    ///
-    /// Log a bookmark to the persistent log.
-    /// \param message_ The Message to log.
-    /// \return the corresponding bookmark sequence number
-    ///         for this bookmark
-    ///
-    size_t log(Message& message_)
-    {
-      if (_body.isValid())
-      {
-        return _body.get().log(message_);
-      }
-      return Message::BOOKMARK_NONE;
-    }
-
-    ///
-    /// Log a discard-bookmark entry to the persistent log
-    /// based on a bookmark sequence number.
-    /// \param subId_ The id of the subscription to which the bookmark applies.
-    /// \param bookmarkSeqNo_ The bookmark sequence number to discard.
-    ///
-    void discard(const Message::Field& subId_, size_t bookmarkSeqNo_)
-    {
-      if (_body.isValid())
-      {
-        _body.get().discard(subId_, bookmarkSeqNo_);
-      }
-    }
-
-    ///
-    /// Log a discard-bookmark entry to the persistent log
-    /// based on a Message.
-    /// \param message_ The message to discard.
-    ///
-    void discard(const Message& message_)
-    {
-      if (_body.isValid())
-      {
-        _body.get().discard(message_);
-      }
-    }
-
-    ///
-    /// Returns the most recent bookmark from the log that
-    /// ought to be used for (re-)subscriptions.
-    /// \param subId_ The id of the subscription to check.
-    /// \return Most recent bookmark.
-    ///
-    Message::Field getMostRecent(const Message::Field& subId_)
-    {
-      if (_body.isValid())
-      {
-        return _body.get().getMostRecent(subId_);
-      }
-      return Message::Field(AMPS_BOOKMARK_EPOCH);
-    }
-
-    ///
-    /// Called for each arriving message to determine if
-    /// the application has already seen this bookmark and should
-    /// not be reprocessed.  Returns 'true' if the bookmark is
-    /// in the log and should not be re-processed, false otherwise.
-    /// \param message_ The Message to check.
-    /// \return Whether or not the bookmark has been discarded.
-    ///
-    bool isDiscarded(Message& message_)
-    {
-      if (_body.isValid())
-      {
-        return _body.get().isDiscarded(message_);
-      }
-      return false;
-    }
-
-    ///
-    /// Called to purge the contents of this store.
-    /// Removes any tracking history associated with publishers and received
-    /// messages, and may delete or truncate on-disk representations as well.
-    ///
-    void purge()
-    {
-      if (_body.isValid())
-      {
-        _body.get().purge();
-      }
-    }
-
-    ///
-    /// Called to purge the contents of this store for particular subId.
-    /// Removes any tracking history associated with publishers and received
-    /// messages, and will remove the subId from the file as well.
-    ///
-    void purge(const Message::Field& subId_)
-    {
-      if (_body.isValid())
-      {
-        _body.get().purge(subId_);
-      }
-    }
-
-    ///
-    /// Set a handler on the bookmark store that will get called whenever
-    /// a resize of the store is required due to the number of stored
-    /// bookmarks exceeding the currently allocated storage to hold them.
-    /// \param handler_ The handler to be called when resizing.
-    /// \param userData_ User data passed to the handler when it is called.
-    void setResizeHandler(BookmarkStoreResizeHandler handler_, void* userData_)
-    {
-      if (_body.isValid())
-      {
-        _body.get().setResizeHandler(handler_, userData_);
-      }
-    }
-
-    ///
-    /// Called to find the oldest bookmark in the store.
-    /// \param subId_ The subscription ID on which to find the oldest bookmark.
-    /// \return The bookmark sequence that is oldest in the store for subId_
-    size_t getOldestBookmarkSeq(const std::string& subId_)
-    {
-      if (_body.isValid())
-        return _body.get().getOldestBookmarkSeq(Message::Field(subId_.c_str(),
-                                                               subId_.length()));
-      return AMPS_UNSET_INDEX;
-    }
-
-    ///
-    /// Called to find the oldest bookmark sequence in the store.
-    /// \param subId_ The subscription ID on which to find the oldest bookmark.
-    /// \return The bookmark sequence that is oldest in the store for subId_
-    size_t getOldestBookmarkSeq(const Message::Field& subId_)
-    {
-      if (_body.isValid())
-      {
-        return _body.get().getOldestBookmarkSeq(subId_);
-      }
-      return AMPS_UNSET_INDEX;
-    }
-
-    /// Called internally to indicate messages up to and including bookmark
-    /// are replicated to all replication destinations.
-    /// \param subId_ The subscription Id to which the bookmark applies.
-    /// \param bookmark_ The most recent bookmark replicated everywhere.
-    void persisted(const Message::Field& subId_, const Message::Field& bookmark_)
-    {
-      if (_body.isValid())
-      {
-        _body.get().persisted(subId_, bookmark_);
-      }
-    }
-
-    /// Called internally to indicate messages up to and including bookmark
-    /// are replicated to all replication destinations.
-    /// \param subId_ The subscription Id to which the bookmark applies.
-    /// \param bookmark_ The most recent bookmark replicated everywhere.
-    void persisted(const Message::Field& subId_, size_t bookmark_)
-    {
-      if (_body.isValid())
-      {
-        _body.get().persisted(subId_, bookmark_);
-      }
-    }
-
-    ///
-    /// Internally used to set the server version so the store knows how to deal
-    /// with persisted acks and calls to getMostRecent().
-    /// \param version_ The version of the server being used.
-    void setServerVersion(size_t version_)
-    {
-      if (_body.isValid())
-      {
-        _body.get().setServerVersion(version_);
-      }
-    }
-
-    ///
-    /// Internally used to set the server version so the store knows how to deal
-    /// with persisted acks and calls to getMostRecent().
-    /// \param version_ The version of the server being used.
-    void setServerVersion(const VersionInfo& version_)
-    {
-      if (_body.isValid())
-      {
-        _body.get().setServerVersion(version_);
-      }
-    }
-
-    ///
-    /// Used to trim the size of a store's storage. Implemented for file-based
-    /// stores to remove items no longer necessary to create the current state.
-    /// \param tmpFileName_ The name to use for the temporary file created
-    /// while pruning the bookmark store.
-    void prune(const std::string& tmpFileName_ = "")
-    {
-      if (_body.isValid())
-      {
-        _body.get().prune(tmpFileName_);
-      }
-    }
-
-    ///
-    /// Used to get a pointer to the implementation.
-    /// \return The BookmarkStoreImpl* for this store's implementation.
-    BookmarkStoreImpl* get()
-    {
-      if (_body.isValid())
-      {
-        return &_body.get();
-      }
-      else
-      {
-        return NULL;
-      }
-    }
-
-    ///
-    /// Gets the maximum allowed length for a sub id when recovering a bookmark
-    /// store from persistent storage.
-    /// \return The maximum length allowed.
-    size_t getMaxSubIdLength() const
-    {
-      if (_body.isValid())
-      {
-        return _body.get().getMaxSubIdLength();
-      }
-      else
-      {
-        return 0;
-      }
-    }
-
-    ///
-    /// Sets the maximum allowed length for a sub id when recovering a bookmark
-    /// store from persistent storage.
-    /// \param maxSubIdLength_ The maximum length allowed.
-    void setMaxSubIdLength(size_t maxSubIdLength_)
-    {
-      if (_body.isValid())
-      {
-        _body.get().setMaxSubIdLength(maxSubIdLength_);
-      }
-    }
-
-  };
-
-  inline bool BookmarkStoreImpl::callResizeHandler(const Message::Field& subId_,
-                                                   size_t newSize_)
-  {
-    if (_resizeHandler)
-    {
-      return _resizeHandler(BookmarkStore(this), subId_, newSize_, _resizeHandlerData);
-    }
-    return true;
-  }
-
-///
-/// A BookmarkStoreResizeHandler that discards the oldest bookmark assuming that it
-/// was used but not discarded when a resize request exceeds size in userData_.
-/// WARNING: Using this handler could cause unseen message loss. This should be used
-/// primarily as a sample and you should write your own version to at least
-/// add some logging.
-  inline bool ThrowawayBookmarkResizeHandler(BookmarkStore store_,
-                                             const Message::Field& subId_,
-                                             size_t newSize_, void* data_)
-  {
-    size_t* maxSizep = (size_t*)data_;
-    if (newSize_ > *maxSizep)
-    {
-      size_t discardSeq = store_.getOldestBookmarkSeq(subId_);
-      store_.discard(subId_, discardSeq);
-      store_.persisted(subId_, discardSeq);
-      return false;
-    }
-    return true;
-  }
-
-}
-
-#endif //_BOOKMARKSTORE_H_
-
-