AMPS C/C++ Client Class Reference
AMPS C/C++ Client Version 5.3.4.4
Special Bookmark Values

The AMPS C++ client includes definitions of special bookmark values. More...

Classes

class  AMPS::BookmarkStoreImpl
 Abstract base class for storing received bookmarks for HA clients. More...
 
class  AMPS::BookmarkStore
 Interface for BookmarkStoreImpl classes. More...
 

Macros

#define AMPS_BOOKMARK_RECENT   "recent"
 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_EPOCH   "0"
 Start the subscription at the beginning of the journal.
 
#define AMPS_BOOKMARK_NOW   "0|1|"
 Start the subscription at the point in time when AMPS processes the subscription.
 

Typedefs

typedef bool(* AMPS::BookmarkStoreResizeHandler) (BookmarkStore store_, const Message::Field &subId_, size_t size_, void *userData_)
 Function type for BookmarkStore resize events The store_ param is store which is resizing. More...
 

Functions

virtual size_t AMPS::BookmarkStoreImpl::log (Message &message_)=0
 Log a bookmark to the persistent log. More...
 
virtual void AMPS::BookmarkStoreImpl::discard (const Message::Field &subId_, size_t bookmarkSeqNo_)=0
 Log a discard-bookmark entry to the persistent log based on a bookmark sequence number. More...
 
virtual void AMPS::BookmarkStoreImpl::discard (const Message &message_)=0
 Log a discard-bookmark entry to the persistent log based on a bookmark sequence number. More...
 
virtual Message::Field AMPS::BookmarkStoreImpl::getMostRecent (const Message::Field &subId_)=0
 Returns the most recent bookmark from the log that ought to be used for (re-)subscriptions. More...
 
virtual bool AMPS::BookmarkStoreImpl::isDiscarded (Message &message_)=0
 Called for each arriving message to determine if the application has already seen this bookmark and should not be reprocessed. More...
 
virtual void AMPS::BookmarkStoreImpl::purge ()=0
 Called to purge the contents of this store. More...
 
virtual void AMPS::BookmarkStoreImpl::purge (const Message::Field &subId_)=0
 Called to purge the contents of this store for particular subId. More...
 
virtual size_t AMPS::BookmarkStoreImpl::getOldestBookmarkSeq (const Message::Field &subId_)=0
 Called to find the oldest bookmark sequence in the store. More...
 
virtual void AMPS::BookmarkStoreImpl::setResizeHandler (BookmarkStoreResizeHandler handler_, void *userData_)
 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. More...
 
virtual void AMPS::BookmarkStoreImpl::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. More...
 
virtual Message::Field AMPS::BookmarkStoreImpl::persisted (const Message::Field &subId_, size_t bookmark_)=0
 Mark the bookmark provided as replicated to all sync replication destinations for the given subscription. More...
 
virtual void AMPS::BookmarkStoreImpl::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(). More...
 
virtual void AMPS::BookmarkStoreImpl::setServerVersion (const VersionInfo &version_)=0
 Internally used to set the server version so the store knows how to deal with persisted acks and calls to getMostRecent(). More...
 
size_t AMPS::BookmarkStoreImpl::getMaxSubIdLength () const
 Gets the maximum allowed length for a sub id when recovering a bookmark store from persistent storage. More...
 
void AMPS::BookmarkStoreImpl::setMaxSubIdLength (size_t maxSubIdLength_)
 Sets the maximum allowed length for a sub id when recovering a bookmark store from persistent storage. More...
 
 AMPS::BookmarkStore::BookmarkStore ()
 Creates a BookmarkStore that does nothing.
 
 AMPS::BookmarkStore::BookmarkStore (BookmarkStoreImpl *impl_)
 Creates a BookmarkStore based on the given implementation.
 
void AMPS::BookmarkStore::setImplementation (BookmarkStoreImpl *impl_)
 Sets the BookmarkStore to use the given implementation.
 
size_t AMPS::BookmarkStore::log (Message &message_)
 Log a bookmark to the persistent log. More...
 
void AMPS::BookmarkStore::discard (const Message::Field &subId_, size_t bookmarkSeqNo_)
 Log a discard-bookmark entry to the persistent log based on a bookmark sequence number. More...
 
void AMPS::BookmarkStore::discard (const Message &message_)
 Log a discard-bookmark entry to the persistent log based on a Message. More...
 
Message::Field AMPS::BookmarkStore::getMostRecent (const Message::Field &subId_)
 Returns the most recent bookmark from the log that ought to be used for (re-)subscriptions. More...
 
bool AMPS::BookmarkStore::isDiscarded (Message &message_)
 Called for each arriving message to determine if the application has already seen this bookmark and should not be reprocessed. More...
 
void AMPS::BookmarkStore::purge ()
 Called to purge the contents of this store. More...
 
void AMPS::BookmarkStore::purge (const Message::Field &subId_)
 Called to purge the contents of this store for particular subId. More...
 
void AMPS::BookmarkStore::setResizeHandler (BookmarkStoreResizeHandler handler_, void *userData_)
 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. More...
 
size_t AMPS::BookmarkStore::getOldestBookmarkSeq (const std::string &subId_)
 Called to find the oldest bookmark in the store. More...
 
size_t AMPS::BookmarkStore::getOldestBookmarkSeq (const Message::Field &subId_)
 Called to find the oldest bookmark sequence in the store. More...
 
void AMPS::BookmarkStore::persisted (const Message::Field &subId_, const Message::Field &bookmark_)
 Called internally to indicate messages up to and including bookmark are replicated to all replication destinations. More...
 
void AMPS::BookmarkStore::persisted (const Message::Field &subId_, size_t bookmark_)
 Called internally to indicate messages up to and including bookmark are replicated to all replication destinations. More...
 
void AMPS::BookmarkStore::setServerVersion (size_t version_)
 Internally used to set the server version so the store knows how to deal with persisted acks and calls to getMostRecent(). More...
 
void AMPS::BookmarkStore::setServerVersion (const VersionInfo &version_)
 Internally used to set the server version so the store knows how to deal with persisted acks and calls to getMostRecent(). More...
 
void AMPS::BookmarkStore::prune (const std::string &tmpFileName_="")
 Used to trim the size of a store's storage. More...
 
BookmarkStoreImplAMPS::BookmarkStore::get ()
 Used to get a pointer to the implementation. More...
 
size_t AMPS::BookmarkStore::getMaxSubIdLength () const
 Gets the maximum allowed length for a sub id when recovering a bookmark store from persistent storage. More...
 
void AMPS::BookmarkStore::setMaxSubIdLength (size_t maxSubIdLength_)
 Sets the maximum allowed length for a sub id when recovering a bookmark store from persistent storage. More...
 
bool AMPS::ThrowawayBookmarkResizeHandler (BookmarkStore store_, const Message::Field &subId_, size_t newSize_, void *data_)
 A BookmarkStoreResizeHandler that discards the oldest bookmark assuming that it was used but not discarded when a resize request exceeds size in userData_. More...
 

Detailed Description

The AMPS C++ client includes definitions of special bookmark values.

These are used with AMPS::Client::bookmarkSubscribe() as values provided to the bookmark parameter.

Typedef Documentation

◆ BookmarkStoreResizeHandler

typedef bool(* AMPS::BookmarkStoreResizeHandler) (BookmarkStore store_, const Message::Field &subId_, size_t size_, void *userData_)

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.

Function Documentation

◆ discard() [1/4]

void AMPS::BookmarkStore::discard ( const Message message_)
inline

Log a discard-bookmark entry to the persistent log based on a Message.

Parameters
message_The message to discard.

◆ discard() [2/4]

virtual void AMPS::BookmarkStoreImpl::discard ( const Message message_)
pure virtual

Log a discard-bookmark entry to the persistent log based on a bookmark sequence number.

Parameters
message_The Message to discard from the store.

Implemented in AMPS::RingBookmarkStore, AMPS::MMapBookmarkStore, AMPS::MemoryBookmarkStore, and AMPS::LoggedBookmarkStore.

◆ discard() [3/4]

void AMPS::BookmarkStore::discard ( const Message::Field subId_,
size_t  bookmarkSeqNo_ 
)
inline

Log a discard-bookmark entry to the persistent log based on a bookmark sequence number.

Parameters
subId_The id of the subscription to which the bookmark applies.
bookmarkSeqNo_The bookmark sequence number to discard.

◆ discard() [4/4]

virtual void AMPS::BookmarkStoreImpl::discard ( const Message::Field subId_,
size_t  bookmarkSeqNo_ 
)
pure virtual

Log a discard-bookmark entry to the persistent log based on a bookmark sequence number.

Parameters
subId_The id of the subscription to which the bookmark applies.
bookmarkSeqNo_The bookmark sequence number to discard.

Implemented in AMPS::RingBookmarkStore, AMPS::MMapBookmarkStore, AMPS::MemoryBookmarkStore, and AMPS::LoggedBookmarkStore.

◆ get()

BookmarkStoreImpl* AMPS::BookmarkStore::get ( )
inline

Used to get a pointer to the implementation.

Returns
The BookmarkStoreImpl* for this store's implementation.

◆ getMaxSubIdLength() [1/2]

size_t AMPS::BookmarkStoreImpl::getMaxSubIdLength ( ) const
inline

Gets the maximum allowed length for a sub id when recovering a bookmark store from persistent storage.

Returns
The maximum length allowed.

◆ getMaxSubIdLength() [2/2]

size_t AMPS::BookmarkStore::getMaxSubIdLength ( ) const
inline

Gets the maximum allowed length for a sub id when recovering a bookmark store from persistent storage.

Returns
The maximum length allowed.

◆ getMostRecent() [1/2]

Message::Field AMPS::BookmarkStore::getMostRecent ( const Message::Field subId_)
inline

Returns the most recent bookmark from the log that ought to be used for (re-)subscriptions.

Parameters
subId_The id of the subscription to check.
Returns
Most recent bookmark.

◆ getMostRecent() [2/2]

virtual Message::Field AMPS::BookmarkStoreImpl::getMostRecent ( const Message::Field subId_)
pure virtual

Returns the most recent bookmark from the log that ought to be used for (re-)subscriptions.

Parameters
subId_The id of the subscription to check.
Returns
Most recent bookmark.

Implemented in AMPS::RingBookmarkStore, AMPS::MMapBookmarkStore, AMPS::MemoryBookmarkStore, and AMPS::LoggedBookmarkStore.

◆ getOldestBookmarkSeq() [1/3]

size_t AMPS::BookmarkStore::getOldestBookmarkSeq ( const Message::Field subId_)
inline

Called to find the oldest bookmark sequence in the store.

Parameters
subId_The subscription ID on which to find the oldest bookmark.
Returns
The bookmark sequence that is oldest in the store for subId_

◆ getOldestBookmarkSeq() [2/3]

virtual size_t AMPS::BookmarkStoreImpl::getOldestBookmarkSeq ( const Message::Field subId_)
pure virtual

Called to find the oldest bookmark sequence in the store.

Parameters
subId_The subscription ID on which to find the oldest bookmark.
Returns
The bookmark sequence that is oldest in the store for subId_

Implemented in AMPS::MemoryBookmarkStore.

◆ getOldestBookmarkSeq() [3/3]

size_t AMPS::BookmarkStore::getOldestBookmarkSeq ( const std::string &  subId_)
inline

Called to find the oldest bookmark in the store.

Parameters
subId_The subscription ID on which to find the oldest bookmark.
Returns
The bookmark sequence that is oldest in the store for subId_

◆ isDiscarded() [1/2]

bool AMPS::BookmarkStore::isDiscarded ( Message message_)
inline

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.

Parameters
message_The Message to check.
Returns
Whether or not the bookmark has been discarded.

◆ isDiscarded() [2/2]

virtual bool AMPS::BookmarkStoreImpl::isDiscarded ( Message message_)
pure virtual

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.

Parameters
message_The Message to check.
Returns
Whether or not the bookmark has been discarded.

Implemented in AMPS::MMapBookmarkStore, AMPS::MemoryBookmarkStore, and AMPS::LoggedBookmarkStore.

◆ log() [1/2]

size_t AMPS::BookmarkStore::log ( Message message_)
inline

Log a bookmark to the persistent log.

Parameters
message_The Message to log.
Returns
the corresponding bookmark sequence number for this bookmark

◆ log() [2/2]

virtual size_t AMPS::BookmarkStoreImpl::log ( Message message_)
pure virtual

Log a bookmark to the persistent log.

Parameters
message_The Message to log in the store.
Returns
the corresponding bookmark sequence number for this bookmark

Implemented in AMPS::RingBookmarkStore, AMPS::MMapBookmarkStore, AMPS::MemoryBookmarkStore, and AMPS::LoggedBookmarkStore.

◆ persisted() [1/4]

void AMPS::BookmarkStore::persisted ( const Message::Field subId_,
const Message::Field bookmark_ 
)
inline

Called internally to indicate messages up to and including bookmark are replicated to all replication destinations.

Parameters
subId_The subscription Id to which the bookmark applies.
bookmark_The most recent bookmark replicated everywhere.

◆ persisted() [2/4]

virtual void AMPS::BookmarkStoreImpl::persisted ( const Message::Field subId_,
const Message::Field bookmark_ 
)
pure virtual

Mark the bookmark provided as replicated to all sync replication destinations for the given subscription.

Parameters
subId_The subscription Id to which the bookmark applies.
bookmark_The most recent replicated bookmark.

Implemented in AMPS::RingBookmarkStore, and AMPS::MemoryBookmarkStore.

◆ persisted() [3/4]

void AMPS::BookmarkStore::persisted ( const Message::Field subId_,
size_t  bookmark_ 
)
inline

Called internally to indicate messages up to and including bookmark are replicated to all replication destinations.

Parameters
subId_The subscription Id to which the bookmark applies.
bookmark_The most recent bookmark replicated everywhere.

◆ persisted() [4/4]

virtual Message::Field AMPS::BookmarkStoreImpl::persisted ( const Message::Field subId_,
size_t  bookmark_ 
)
pure virtual

Mark the bookmark provided as replicated to all sync replication destinations for the given subscription.

Parameters
subId_The subscription Id to which the bookmark applies.
bookmark_The most recent bookmark's sequence number.
Returns
The bookmark field that was just marked persisted.

Implemented in AMPS::MemoryBookmarkStore.

◆ prune()

void AMPS::BookmarkStore::prune ( const std::string &  tmpFileName_ = "")
inline

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.

Parameters
tmpFileName_The name to use for the temporary file created while pruning the bookmark store.

◆ purge() [1/4]

void AMPS::BookmarkStore::purge ( )
inline

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.

◆ purge() [2/4]

virtual void AMPS::BookmarkStoreImpl::purge ( )
pure virtual

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.

Implemented in AMPS::RingBookmarkStore, AMPS::MMapBookmarkStore, AMPS::MemoryBookmarkStore, and AMPS::LoggedBookmarkStore.

◆ purge() [3/4]

void AMPS::BookmarkStore::purge ( const Message::Field subId_)
inline

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.

◆ purge() [4/4]

virtual void AMPS::BookmarkStoreImpl::purge ( const Message::Field subId_)
pure virtual

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.

Implemented in AMPS::RingBookmarkStore, AMPS::MMapBookmarkStore, AMPS::MemoryBookmarkStore, and AMPS::LoggedBookmarkStore.

◆ setMaxSubIdLength() [1/2]

void AMPS::BookmarkStoreImpl::setMaxSubIdLength ( size_t  maxSubIdLength_)
inline

Sets the maximum allowed length for a sub id when recovering a bookmark store from persistent storage.

Parameters
maxSubIdLength_The maximum length allowed.

◆ setMaxSubIdLength() [2/2]

void AMPS::BookmarkStore::setMaxSubIdLength ( size_t  maxSubIdLength_)
inline

Sets the maximum allowed length for a sub id when recovering a bookmark store from persistent storage.

Parameters
maxSubIdLength_The maximum length allowed.

◆ setResizeHandler() [1/2]

virtual void AMPS::BookmarkStoreImpl::setResizeHandler ( BookmarkStoreResizeHandler  handler_,
void *  userData_ 
)
inlinevirtual

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.

Parameters
handler_The handler to be called when resizing.
userData_User data passed to the handler when it is called.

◆ setResizeHandler() [2/2]

void AMPS::BookmarkStore::setResizeHandler ( BookmarkStoreResizeHandler  handler_,
void *  userData_ 
)
inline

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.

Parameters
handler_The handler to be called when resizing.
userData_User data passed to the handler when it is called.

◆ setServerVersion() [1/4]

void AMPS::BookmarkStore::setServerVersion ( const VersionInfo &  version_)
inline

Internally used to set the server version so the store knows how to deal with persisted acks and calls to getMostRecent().

Parameters
version_The version of the server being used.

◆ setServerVersion() [2/4]

virtual void AMPS::BookmarkStoreImpl::setServerVersion ( const VersionInfo &  version_)
pure virtual

Internally used to set the server version so the store knows how to deal with persisted acks and calls to getMostRecent().

Parameters
version_The version of the server being used.

Implemented in AMPS::MMapBookmarkStore, AMPS::MemoryBookmarkStore, and AMPS::LoggedBookmarkStore.

◆ setServerVersion() [3/4]

void AMPS::BookmarkStore::setServerVersion ( size_t  version_)
inline

Internally used to set the server version so the store knows how to deal with persisted acks and calls to getMostRecent().

Parameters
version_The version of the server being used.

◆ setServerVersion() [4/4]

virtual void AMPS::BookmarkStoreImpl::setServerVersion ( size_t  version_)
pure virtual

Internally used to set the server version so the store knows how to deal with persisted acks and calls to getMostRecent().

Parameters
version_The version of the server being used.

Implemented in AMPS::MMapBookmarkStore, AMPS::MemoryBookmarkStore, and AMPS::LoggedBookmarkStore.

◆ ThrowawayBookmarkResizeHandler()

bool AMPS::ThrowawayBookmarkResizeHandler ( BookmarkStore  store_,
const Message::Field subId_,
size_t  newSize_,
void *  data_ 
)
inline

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.