Using PubSub+ Cache With the C API

When a session has been established with a Solace PubSub+ event broker, a client application can create a cache session and then make requests for cached messages (that is, cache requests).

The basic steps to make a cache request in a session are:

1. Create a cache session. Refer to Creating Cache Sessions.
2. Send a cache request. Refer to Sending Cache Requests.
3. Receive requested cached messages. Refer to Receiving Cached Messages.
4. Destroy the cache session. Refer to Destroying Cache Sessions.

Creating Cache Sessions

A cache session contains static cache properties and cache state information, and it allows multiple outstanding cache requests and synchronizes those requests.

To create a cache session in a connected session, call the solClient_session_
createCacheSession() function and pass in the cache session properties listed below. A single session can have many cache sessions.

Cache Session Properties

Parameter	Description
SOLCLIENT_CACHESESSION_PROP_ CACHE_NAME	The identifying name of the Distributed Cache, Cache Cluster, or PubSub+ Cache Instance to send the cache requests to. Specifying the Distributed Cache is the preferred method because specifying a PubSub+ Cache Instance bypasses redundancy and load balancing of cache requests.
SOLCLIENT_CACHESESSION_PROP_ MAX_AGE	The maximum age (in seconds) of the messages to retrieve. Messages that have been cached for more than this amount of time are not retrieved. A value of 0 returns all possible messages for the topic, as defined by SOLCLIENT_ CACHESESSION_PROP_MAX_MSGS.
SOLCLIENT_CACHESESSION_PROP_ MAX_MSGS	The maximum number of cached messages to retrieve for any one topic. If more messages are cached for a topic than the maximum value, the newest messages are returned. A value of 0 retrieves all messages newer than SOLCLIENT_CACHESESSION_PROP_MAX_AGE.
SOLCLIENT_CACHESESSION_PROP_ REPLY_TO	The reply-to topic for the cache request. For most situations, it is recommended that this property be left unspecified so that the API uses the session P2P Reply To Topic. (For more information, refer to SOLCLIENT_SESSION_PROP_ P2PINBOX_IN_USE in the PubSub+ Messaging API C reference).
SOLCLIENT_CACHESESSION_PROP_ REQUESTREPLY_TIMEOUT_MS	The amount of time (in milliseconds) to wait for a response to the cache request from the cache. This is a per-request timeout where each request sent by the application could result in multiple underlying requests.

Sending Cache Requests

To send a blocking and non-blocking cache request for messages published to a specific topic, call solClient_cacheSession_sendCacheRequest() and pass in the parameters listed in the table below.

It is up to the client to deal with request timeouts as it is possible that Cache Clusters, event brokers, or individual PubSub+ Cache Instances may fail or disconnect in the middle of cache request processing. The cache response indicates whether the PubSub+ Cache Instance is in a lost message state. Refer to Lost Message State for details.

Cache Request Message Parameters

Parameter	Description
opaqueCacheSession_p	The opaque cache session pointer returned when the cache session was created.
topic_p	The topic for which messages are requested from the cache. Use of #noexport is not supported in the topic. Wildcard cache requests are only supported for FLOW_THRU cache requests. When a wildcard request matches multiple cached subjects, there are no temporal ordering guarantees between the individual topics returned (although temporal ordering will still be preserved amongst the messages for a specific topic).
cacheRequestId	A 64-bit integer provided by the application that is returned to the application in the cache request response. The request ID is also available in every cached message returned.
callback_p	A callback pointer for a no-wait (that is non‑blocking) reply to cache requests.
user_p	A user pointer to return with a callback.
cacheflags	Flags that are used to further define the cache request behavior. For list of the available flags and their descriptions, refer to the following table.
subscribeflags	The subscription flags for a subscription made through a cache request are the same as those made through a regular topic subscription. For more information, refer to the documentation provided for solClient_session_ topicSubscribeExt in the PubSub+ Messaging API C reference. When the cache request flag SOLCLIENT_ CACHEREQUEST_FLAGS_NO_SUBSCRIBE is set, subscription flags are ignored.

The following table lists the optional flags that can be set on a cache request.

When sending cache requests you must always specify one and only one of the LIVEDATA flag options (there is no default).

Cache Request Flags

Parameter	Description
SOLCLIENT_CACHEREQUEST_FLAGS_ NO_SUBSCRIBE	If this flag is set, do not include a subscription to the event broker with the cache request. Only send a cache request to the Cache Cluster. By default, a subscription is automatically added for the topic then the cache request is added. By adding the subscription, the client will receive relevant live data messages after it has received all of the cached messages.
SOLCLIENT_CACHEREQUEST_FLAGS_ LIVEDATA_FULFILL	If this flag is set, when live data that matches the outstanding cache request topic arrives before the cache response, allow the live data to fulfill the cache request. Any subsequent matching cached data messages are discarded.
SOLCLIENT_CACHEREQUEST_FLAGS_ LIVEDATA_QUEUE	If this flag is set, queue received live data messages that match the cache request topic until the cache request completes.
SOLCLIENT_CACHEREQUEST_FLAGS_ LIVEDATA_FLOWTHRU	If this flag is set, received live data messages that match the cache request topic are passed through to the application. A cache request can remain outstanding while live data messages are being passed through. The subsequent matching cached data messages are also delivered to the application. The SOLCLIENT_CACHEREQUEST_FLAGS_ LIVEDATA_FLOWTHRU flag must be set for wildcard cache requests.
SOLCLIENT_CACHEREQUEST_FLAGS_ NOWAIT_REPLY	If this flag is set, the cache request returns immediately with the SOLCLIENT_IN_PROGRESS event; when the cache request completes, its status is returned through a callback. By default, this flag is not set, and the send cache request function blocks until the cache request is complete.

Receiving Cached Messages

Cached messages are received through the rxMsgCallbackFunc_t callback. The API does not attempt to reorder cached messages that are received across different Cache Clusters. In addition, the API does not attempt to drop duplicate messages received from Cache Clusters or live publishers.

Messages in cache responses may be bundled together by the cache, but they are delivered to applications individually by the messaging API.

If an application registers an event callback pointer with cache requests flagged as SOLCLIENT_CACHEREQUEST_FLAGS_NOWAIT_REPLY (that is, non-blocking), the cache request status is returned in the solCache_eventCallbackInfo solCache_eventCallbackInfo_t structure.

The following table lists the return codes that can be returned. Although these codes are also returned for non-cache request API calls for clients connecting to an event broker, the provided descriptions indicate what the events signify for a cache request.

Cache Request Events

Event	Description
SOLCLIENT_OK	Indicates that: the cache replies were all received before the timer expired none of the received cached messages were suspect at least one cache reply had data
SOLCLIENT_INCOMPLETE	Indicates that incomplete data has been returned. Reasons might include: all of the cache replies contained no data at least one message was suspect
SOLCLIENT_FAIL	Indicates that an error occurred during the initial cache request. Possible reasons include: timeout waiting for a cache response a cache error response an add subscription error response a transport error when communicating with the event broker If an error occurs after the initial cache request (for example, when communicating with other PubSub+ Cache instances in the Cache Cluster), then SOLCLIENT_INCOMPLETE is returned. If a failure occurs, the API does not automatically retry any outstanding cache requests. In addition, if there is a loss of connection with the event broker, any outstanding cache requests are canceled.

Destroying Cache Sessions

To cancel all outstanding requests and destroy the cache session, call the solClient_cacheSession_destroy() function. It is safe to call this function from any thread.

When solClient_cacheSession_destroy() is called, the following occurs:

• all outstanding cache requests are canceled
• live messages that have been queued are delivered
• all blocked synchronous cache requests return immediately with an INCOMPLETE return code, a SOLCLIENT_SUBCODE_PARAM_NULL_PTR subcode, and a “Cache session has been destroyed” error string
• no event is generated for in-progress asynchronous cache requests

Canceling Cache Requests

To cancel all outstanding requests, without destroying the cache session, call the solClient_cacheSession_cancelCacheRequests() function. It is safe to call this function from any thread, and it can be called repeatedly.

When solClient_cacheSession_cancelCacheRequests() is called, the following occurs:

• all outstanding cache requests are canceled.
• all live messages that have been queued are delivered
• all blocked synchronous cache requests return immediately with an INCOMPLETE return code and a SOLCLIENT_SUBCODE_CACHE_REQUEST_CANCELLED subcode
• a cache event SOLCACHE_EVENT_REQUEST_COMPLETED_NOTICE with a subcode of SOLCLIENT_SUBCODE_CACHE_REQUEST_CANCELLED is generated for each in‑progress asynchronous cache request