OpenMAMA C++ API
Wombat::MamaSubscription Class Reference

The MamaSubscription interface represents a subscription to a topic. More...

#include <MamaSubscription.h>

Inheritance diagram for Wombat::MamaSubscription:
Wombat::MamaBasicSubscription

Public Member Functions

virtual ~MamaSubscription ()
 
 MamaSubscription (void)
 
virtual void setCSubscription (mamaSubscription subscription)
 
virtual mamaSubscription getCSubscription ()
 
virtual void setup (MamaTransport *transport, MamaQueue *queue, MamaSubscriptionCallback *callback, const char *source, const char *symbol, void *closure=NULL)
 Set up a subscription. More...
 
virtual void setup (MamaQueue *queue, MamaSubscriptionCallback *callback, MamaSource *source, const char *symbol, void *closure=NULL)
 Set up a subscription. More...
 
virtual void activate ()
 Activate a subscriber using the throttle queue. More...
 
virtual void deactivate ()
 Deactivate a subscriber. More...
 
virtual void create (MamaTransport *transport, MamaQueue *queue, MamaSubscriptionCallback *callback, const char *source, const char *symbol, void *closure=NULL)
 Set up and activate a subscriber using the throttle queue. More...
 
virtual void create (MamaQueue *queue, MamaSubscriptionCallback *callback, MamaSource *source, const char *symbol, void *closure=NULL)
 Set up and activate a subscriber using the throttle queue. More...
 
virtual void createSnapshot (MamaTransport *transport, MamaQueue *queue, MamaSubscriptionCallback *callback, const char *source, const char *symbol, void *closure=NULL)
 Set up and activate a snapshot subscriber using the throttle queue. More...
 
virtual void setRequiresInitial (bool requiresInitial)
 Determines whether the subscription requires an initial value. More...
 
virtual bool getRequiresInitial (void)
 Return true if the subscription requires an initial value. More...
 
virtual bool getReceivedInitial (void)
 Return true if the subscription has received an initial. More...
 
virtual void setRetries (int retries)
 Set the number of retries for initial value requests and recap requests. More...
 
virtual int getRetries (void)
 Return the retries. More...
 
virtual void setSubscriptionType (mamaSubscriptionType type)
 Set the subscription type. More...
 
virtual mamaSubscriptionType getSubscriptionType (void)
 Return the subscription type. More...
 
virtual long getServiceLevelOpt (void)
 Return the service level option. More...
 
virtual void setServiceLevel (mamaServiceLevel svcLevel, long svcLevelOpt)
 Set the service level. More...
 
virtual mamaServiceLevel getServiceLevel (void)
 Return the service level. More...
 
virtual const char * getSymbol (void) const
 Return the symbol for this subscription. More...
 
virtual MamaSubscriptionCallbackgetCallback (void) const
 
virtual void setSymbol (const char *symbol)
 Sets the symbol for this subscription. More...
 
virtual const MamaSourceDerivativegetSourceDerivative (void) const
 Return the (subscription-specific) MAMA source derivative for this subscription. More...
 
virtual MamaSourceDerivativegetSourceDerivative (void)
 Return the (subscription-specific) MAMA source derivative for this subscription. More...
 
virtual const MamaSourcegetSource (void) const
 Return the MAMA source for this subscription. More...
 
virtual const char * getSubscSource (void) const
 Return the source for this subscription. More...
 
virtual void setTimeout (double timeout)
 Set the timeout for this subscription. More...
 
virtual double getTimeout (void)
 Return the timeout. More...
 
virtual void setRecapTimeout (double timeout)
 Set the timeout for this subscription. More...
 
virtual double getRecapTimeout (void)
 Return the recap timeout. More...
 
virtual void setRecoverGaps (bool recover)
 Attempt to recover from sequence number gaps by requesting a recap. More...
 
virtual bool getRecoverGaps (void) const
 Returns true if listener is configure to recover from sequence number gaps by requesting a recap. More...
 
virtual void setAppDataType (uint8_t dataType)
 Set the application data type. More...
 
virtual uint8_t getAppDataType () const
 Get the application data type. More...
 
virtual void setGroupSizeHint (int groupSizeHint)
 Set a hint to the size of groups when making group subscriptions. More...
 
virtual void setItemClosure (void *closure)
 Set the item closure for group subscriptions. More...
 
virtual void * getItemClosure (void)
 Get the item closure for group subscriptions. More...
 
virtual void setPreInitialCacheSize (int cacheSize)
 Set the number of messages to cache for each symbol before the initial value arrives. More...
 
virtual int getPreInitialCacheSize (void)
 Return the initial value cache size. More...
 
virtual void setMsgQualifierFilter (bool ignoreDefinitelyDuplicate, bool ignorePossiblyDuplicate, bool ignoreDefinitelyDelyaed, bool ignorePossiblyDelayed, bool ignoreOutOfSequence)
 Set a filter to discard messages. More...
 
virtual void getMsgQualifierFilter (bool &ignoreDefinitelyDuplicate, bool &ignorePossiblyDuplicate, bool &ignoreDefinitelyDelyaed, bool &ignorePossiblyDelayed, bool &ignoreOutOfSequence) const
 Get the filters that discard message according to the message qualifier. More...
 
virtual void destroy ()
 Destroy the subscription. More...
 
virtual void destroyEx ()
 This function will destroy the subscription and can be called from any thread. More...
 
- Public Member Functions inherited from Wombat::MamaBasicSubscription
virtual ~MamaBasicSubscription ()
 The destructor will call destroy() if the subscription has not already been destroyed. More...
 
 MamaBasicSubscription (void)
 Constructor. More...
 
virtual void createBasic (MamaTransport *transport, MamaQueue *queue, MamaBasicSubscriptionCallback *callback, const char *topic, void *closure=NULL)
 Create a basic subscription without market data semantics. More...
 
virtual bool isActive (void) const
 Return whether the subscription is active. More...
 
virtual const char * getTopic (void) const
 Return the symbol for this subscription. More...
 
virtual MamaTransportgetTransport (void) const
 Return the MamaTransport for this subscription. More...
 
virtual MamaBasicSubscriptionCallbackgetBasicCallback (void) const
 Return the MamaSubscriptionCallback for this subscription. More...
 
virtual MamaQueuegetQueue (void) const
 Return the MamaQueue for the subscription. More...
 
virtual void setClosure (void *closure)
 Set the closure for the subscription. More...
 
virtual void * getClosure (void) const
 Return the closure for the subscription. More...
 
virtual void setDebugLevel (MamaLogLevel level)
 Set the debug level for this subscription. More...
 
virtual MamaLogLevel getDebugLevel () const
 Return the debug level for this subscription. More...
 
virtual bool checkDebugLevel (MamaLogLevel level) const
 Return whether the debug level for this subscription equals or exceeds some level. More...
 
virtual mamaSubscriptionState getState (void)
 This function will return the current state of the subscription, this function should be used in preference to the mamaSubscription_isActive or mamaSubscription_isValid functions. More...
 

Additional Inherited Members

- Protected Attributes inherited from Wombat::MamaBasicSubscription
void * mClosure
 
MamaQueuemQueue
 
mamaSubscription mSubscription
 
MamaTransportmTransport
 

Detailed Description

The MamaSubscription interface represents a subscription to a topic.

It provides transparent market data semantics and functionality including initial value requests, recap requests, subscription management and data quality.

Constructor & Destructor Documentation

§ ~MamaSubscription()

virtual Wombat::MamaSubscription::~MamaSubscription ( )
virtual

§ MamaSubscription()

Wombat::MamaSubscription::MamaSubscription ( void  )

Member Function Documentation

§ setCSubscription()

virtual void Wombat::MamaSubscription::setCSubscription ( mamaSubscription  subscription)
virtual

§ getCSubscription()

virtual mamaSubscription Wombat::MamaSubscription::getCSubscription ( )
virtual

§ setup() [1/2]

virtual void Wombat::MamaSubscription::setup ( MamaTransport transport,
MamaQueue queue,
MamaSubscriptionCallback callback,
const char *  source,
const char *  symbol,
void *  closure = NULL 
)
virtual

Set up a subscription.

Parameters
callbackThe callback.
transportThe transport.
queueThe mama queue.
sourceThe data source name for the listener.
symbolThe symbol for the listener.
closureThe caller supplied closure.

§ setup() [2/2]

virtual void Wombat::MamaSubscription::setup ( MamaQueue queue,
MamaSubscriptionCallback callback,
MamaSource source,
const char *  symbol,
void *  closure = NULL 
)
virtual

Set up a subscription.

Parameters
queueThe mama queue.
callbackThe callback.
sourceThe MamaSource identifying the publisher for this symbol.
symbolThe symbol for the listener.
closureThe caller supplied closure.

§ activate()

virtual void Wombat::MamaSubscription::activate ( )
virtual

Activate a subscriber using the throttle queue.

This method places a request to create a subscriber on the throttle queue which dispatches tasks that produce messages at a controlled rate. The rate is determined by the outbound throttle rate of the underlying MamaTransport.

In the event that listener creation fails as the result of an messaging related error the callback is invoked with information regarding the error.

If entitlements are enabled, and the caller is not entitled to the requested symbol, the first invocation of the callback will invoked with status "MamaMsgStatus.NOT_ENTITLED".

As an added convenience, callers may implement the onComplete and onError members of MamaSubscriptionCallback. onComplete is invoked prior to the arrival of any initial message signalling the successful creation of the listener. onError is invoked if a TIBRV or entitlement error occurs prior to listener creation.

It is also possible for an entitlement error to occur after a listener is created. This occurs when the entitlement information is included in the initial message sent by the feed handler as is often the case.

If an error occurs during listener creation. destroy is called automatically.

§ deactivate()

virtual void Wombat::MamaSubscription::deactivate ( )
virtual

Deactivate a subscriber.

The subscription can be reactivated using activate().

§ create() [1/2]

virtual void Wombat::MamaSubscription::create ( MamaTransport transport,
MamaQueue queue,
MamaSubscriptionCallback callback,
const char *  source,
const char *  symbol,
void *  closure = NULL 
)
virtual

Set up and activate a subscriber using the throttle queue.

This method is equivalent to calling setup() followed by activate().

Parameters
transportThe transport.
queueThe mama queue.
callbackThe callback.
sourceThe data source name for the listener.
symbolThe symbol for the listener.
closureThe caller supplied closure.

§ create() [2/2]

virtual void Wombat::MamaSubscription::create ( MamaQueue queue,
MamaSubscriptionCallback callback,
MamaSource source,
const char *  symbol,
void *  closure = NULL 
)
virtual

Set up and activate a subscriber using the throttle queue.

This method is equivalent to calling setup() followed by activate().

Parameters
queueThe mama queue.
callbackThe callback.
sourceThe MamaSource identifying the publisher for this symbol.
symbolThe symbol for the listener.
closureThe caller supplied closure.

§ createSnapshot()

virtual void Wombat::MamaSubscription::createSnapshot ( MamaTransport transport,
MamaQueue queue,
MamaSubscriptionCallback callback,
const char *  source,
const char *  symbol,
void *  closure = NULL 
)
virtual

Set up and activate a snapshot subscriber using the throttle queue.

This method is equivalent to calling setup() followed by setServiceLevel(MAMA_SERVICE_LEVEL_SNAPSHOT,0) followed by activate().

Parameters
transportThe transport.
queueThe mama queue.
callbackThe callback.
sourceThe data source name for the listener.
symbolThe symbol for the listener.
closureThe caller supplied closure.

§ setRequiresInitial()

virtual void Wombat::MamaSubscription::setRequiresInitial ( bool  requiresInitial)
virtual

Determines whether the subscription requires an initial value.

Must be set before calling createXXX(). Default is true. Not applicable for snapshot subscriptions as they simply request an initial value.

Parameters
requiresInitialTrue if an initial value is required

§ getRequiresInitial()

virtual bool Wombat::MamaSubscription::getRequiresInitial ( void  )
virtual

Return true if the subscription requires an initial value.

§ getReceivedInitial()

virtual bool Wombat::MamaSubscription::getReceivedInitial ( void  )
virtual

Return true if the subscription has received an initial.

§ setRetries()

virtual void Wombat::MamaSubscription::setRetries ( int  retries)
virtual

Set the number of retries for initial value requests and recap requests.

This must called before createXXX() to affect the initial value requests. Calling it after createXXX() only affects recap requests. The default is MAMA_DEFAULT_RETRIES.

Parameters
retriesThe number of time to retry the initial value request.

§ getRetries()

virtual int Wombat::MamaSubscription::getRetries ( void  )
virtual

Return the retries.

§ setSubscriptionType()

virtual void Wombat::MamaSubscription::setSubscriptionType ( mamaSubscriptionType  type)
virtual

Set the subscription type.

The default is normal.

Parameters
typeThe type of subscription (normal, group, order book, etc.).

§ getSubscriptionType()

virtual mamaSubscriptionType Wombat::MamaSubscription::getSubscriptionType ( void  )
virtual

Return the subscription type.

§ getServiceLevelOpt()

virtual long Wombat::MamaSubscription::getServiceLevelOpt ( void  )
virtual

Return the service level option.

§ setServiceLevel()

virtual void Wombat::MamaSubscription::setServiceLevel ( mamaServiceLevel  svcLevel,
long  svcLevelOpt 
)
virtual

Set the service level.

This method must be invoked before createXXX().

Parameters
svcLevelThe service level of the subscription (real time, snapshot, etc.). The default is real time.
svcLevelOptAn optional argument for certain service levels.

§ getServiceLevel()

virtual mamaServiceLevel Wombat::MamaSubscription::getServiceLevel ( void  )
virtual

Return the service level.

§ getSymbol()

virtual const char* Wombat::MamaSubscription::getSymbol ( void  ) const
virtual

Return the symbol for this subscription.

Returns
The topic.

§ getCallback()

virtual MamaSubscriptionCallback* Wombat::MamaSubscription::getCallback ( void  ) const
virtual

§ setSymbol()

virtual void Wombat::MamaSubscription::setSymbol ( const char *  symbol)
virtual

Sets the symbol for this subscription.

Should generally only be used for updating symbology mappings.

§ getSourceDerivative() [1/2]

virtual const MamaSourceDerivative* Wombat::MamaSubscription::getSourceDerivative ( void  ) const
virtual

Return the (subscription-specific) MAMA source derivative for this subscription.

Returns
The source derivative.

§ getSourceDerivative() [2/2]

virtual MamaSourceDerivative* Wombat::MamaSubscription::getSourceDerivative ( void  )
virtual

Return the (subscription-specific) MAMA source derivative for this subscription.

Returns
The source derivative.

§ getSource()

virtual const MamaSource* Wombat::MamaSubscription::getSource ( void  ) const
virtual

Return the MAMA source for this subscription.

Returns
The source.

§ getSubscSource()

virtual const char* Wombat::MamaSubscription::getSubscSource ( void  ) const
virtual

Return the source for this subscription.

Returns
The source.

§ setTimeout()

virtual void Wombat::MamaSubscription::setTimeout ( double  timeout)
virtual

Set the timeout for this subscription.

The timeout is used for requesting initial values.

Parameters
timeoutThe timeout in seconds.

§ getTimeout()

virtual double Wombat::MamaSubscription::getTimeout ( void  )
virtual

Return the timeout.

§ setRecapTimeout()

virtual void Wombat::MamaSubscription::setRecapTimeout ( double  timeout)
virtual

Set the timeout for this subscription.

The timeout is used for requesting recaps.

Parameters
timeoutThe timeout in seconds.

§ getRecapTimeout()

virtual double Wombat::MamaSubscription::getRecapTimeout ( void  )
virtual

Return the recap timeout.

§ setRecoverGaps()

virtual void Wombat::MamaSubscription::setRecoverGaps ( bool  recover)
virtual

Attempt to recover from sequence number gaps by requesting a recap.

Parameters
recovertrue enables recovery attempts.

§ getRecoverGaps()

virtual bool Wombat::MamaSubscription::getRecoverGaps ( void  ) const
virtual

Returns true if listener is configure to recover from sequence number gaps by requesting a recap.

Returns
true if gap recover is enabled.

§ setAppDataType()

virtual void Wombat::MamaSubscription::setAppDataType ( uint8_t  dataType)
virtual

Set the application data type.

The default is 0.

Parameters
dataTypeThe application-specific data type (e.g., market data).

§ getAppDataType()

virtual uint8_t Wombat::MamaSubscription::getAppDataType ( ) const
virtual

Get the application data type.

The default is 0.

Returns
The application-specific data type (e.g., market data).

§ setGroupSizeHint()

virtual void Wombat::MamaSubscription::setGroupSizeHint ( int  groupSizeHint)
virtual

Set a hint to the size of groups when making group subscriptions.

Parameters
groupSizeHintApproximate expected group size

§ setItemClosure()

virtual void Wombat::MamaSubscription::setItemClosure ( void *  closure)
virtual

Set the item closure for group subscriptions.

Group subscriptions receive updates for multiple symbols. This method allows calls to set a per-symbol closure which will be passed as the fourth argument to subsequent calls to the onMsg callback. This method may only be called during the onMsg callback.

Setting the item closure for a non-group subscription provides a second closure.

§ getItemClosure()

virtual void* Wombat::MamaSubscription::getItemClosure ( void  )
virtual

Get the item closure for group subscriptions.

See setItemClosure. When invoked during an onMsg callback this method returns the closure for the current item in a group subscription. When invoked outside an onMsg callback, it returns the closure from the most recent callback.

§ setPreInitialCacheSize()

virtual void Wombat::MamaSubscription::setPreInitialCacheSize ( int  cacheSize)
virtual

Set the number of messages to cache for each symbol before the initial value arrives.

This allows the subscription to recover when the initial value arrives late (after a subsequent trade or quote already arrived).

For group subscription, a separate cache is used for each group member.

The default is 10.

Parameters
cacheSizeThe size of the cache.

§ getPreInitialCacheSize()

virtual int Wombat::MamaSubscription::getPreInitialCacheSize ( void  )
virtual

Return the initial value cache size.

Returns
The cache size.

§ setMsgQualifierFilter()

virtual void Wombat::MamaSubscription::setMsgQualifierFilter ( bool  ignoreDefinitelyDuplicate,
bool  ignorePossiblyDuplicate,
bool  ignoreDefinitelyDelyaed,
bool  ignorePossiblyDelayed,
bool  ignoreOutOfSequence 
)
virtual

Set a filter to discard messages.

Parameters
ignoreDefinitelyDuplicateIf true callbacks will not be invoked for messages where MamaMsg::getIsDefinitelyDuplicate returns true.
ignorePossiblyDuplicateIf true callbacks will not be invoked for messages where MamaMsg::getIsPossiblyDuplicate returns true.
ignoreDefinitelyDelyaedIf true callbacks will not be invoked for messages where MamaMsg::getIsDefinitelyDelayed returns true.
ignorePossiblyDelayedIf true callbacks will not be invoked for messages where MamaMsg::getIsPossiblyDelayed returns true.
ignoreOutOfSequenceIf true callbacks will not be invoked for messages where MamaMsg::getIsOutOfSequence returns true.

§ getMsgQualifierFilter()

virtual void Wombat::MamaSubscription::getMsgQualifierFilter ( bool &  ignoreDefinitelyDuplicate,
bool &  ignorePossiblyDuplicate,
bool &  ignoreDefinitelyDelyaed,
bool &  ignorePossiblyDelayed,
bool &  ignoreOutOfSequence 
) const
virtual

Get the filters that discard message according to the message qualifier.

Parameters
ignoreDefinitelyDuplicateIf true callbacks will not be invoked for messages where MamaMsg::getIsDefinitelyDuplicate returns true.
ignorePossiblyDuplicateIf true callbacks will not be invoked for messages where MamaMsg::getIsPossiblyDuplicate returns true.
ignoreDefinitelyDelayedIf true callbacks will not be invoked for messages where MamaMsg::getIsDefinitelyDelayed returns true.
ignorePossiblyDelayedIf true callbacks will not be invoked for messages where MamaMsg::getIsPossiblyDelayed returns true.
ignoreOutOfSequenceIf true callbacks will not be invoked for messages where MamaMsg::getIsOutOfSequence returns true.

§ destroy()

virtual void Wombat::MamaSubscription::destroy ( )
virtual

Destroy the subscription.

Destroys the underlying subscription. The subscription can be recreated via a subsequent call to create()

Reimplemented from Wombat::MamaBasicSubscription.

§ destroyEx()

virtual void Wombat::MamaSubscription::destroyEx ( )
virtual

This function will destroy the subscription and can be called from any thread.

Note that the subscription will not be fully destroyed until the onDestroy callback is received from the MamaBasicSubscriptionCallback interface. To destroy from the dispatching thread the destroy function should be used in preference.

Reimplemented from Wombat::MamaBasicSubscription.