Subscription

Functions
NATS_EXTERN natsStatus	natsSubscription_NoDeliveryDelay (natsSubscription *sub)
	Enables the No Delivery Delay mode.
NATS_EXTERN natsStatus	natsSubscription_NextMsg (natsMsg **nextMsg, natsSubscription *sub, int64_t timeout)
	Returns the next available message.
NATS_EXTERN natsStatus	natsSubscription_Unsubscribe (natsSubscription *sub)
	Unsubscribes.
NATS_EXTERN natsStatus	natsSubscription_AutoUnsubscribe (natsSubscription *sub, int max)
	Auto-Unsubscribes.
NATS_EXTERN natsStatus	natsSubscription_QueuedMsgs (natsSubscription *sub, uint64_t *queuedMsgs)
	Gets the number of pending messages.
NATS_EXTERN int64_t	natsSubscription_GetID (natsSubscription *sub)
	Gets the subscription id.
NATS_EXTERN const char *	natsSubscription_GetSubject (natsSubscription *sub)
	Gets the subject name.
NATS_EXTERN natsStatus	natsSubscription_SetPendingLimits (natsSubscription *sub, int msgLimit, int bytesLimit)
	Sets the limit for pending messages and bytes.
NATS_EXTERN natsStatus	natsSubscription_GetPendingLimits (natsSubscription *sub, int *msgLimit, int *bytesLimit)
	Returns the current limit for pending messages and bytes.
NATS_EXTERN natsStatus	natsSubscription_GetPending (natsSubscription *sub, int *msgs, int *bytes)
	Returns the number of pending messages and bytes.
NATS_EXTERN natsStatus	natsSubscription_GetDelivered (natsSubscription *sub, int64_t *msgs)
	Returns the number of delivered messages.
NATS_EXTERN natsStatus	natsSubscription_GetDropped (natsSubscription *sub, int64_t *msgs)
	Returns the number of dropped messages.
NATS_EXTERN natsStatus	natsSubscription_GetMaxPending (natsSubscription *sub, int *msgs, int *bytes)
	Returns the maximum number of pending messages and bytes.
NATS_EXTERN natsStatus	natsSubscription_ClearMaxPending (natsSubscription *sub)
	Clears the statistics regarding the maximum pending values.
NATS_EXTERN natsStatus	natsSubscription_GetStats (natsSubscription *sub, int *pendingMsgs, int *pendingBytes, int *maxPendingMsgs, int *maxPendingBytes, int64_t *deliveredMsgs, int64_t *droppedMsgs)
	Get various statistics from this subscription.
NATS_EXTERN bool	natsSubscription_IsValid (natsSubscription *sub)
	Checks the validity of the subscription.
NATS_EXTERN natsStatus	natsSubscription_Drain (natsSubscription *sub)
	Drains the subscription with a default timeout.
NATS_EXTERN natsStatus	natsSubscription_DrainTimeout (natsSubscription *sub, int64_t timeout)
	Drains the subscription with the specified timeout.
NATS_EXTERN natsStatus	natsSubscription_WaitForDrainCompletion (natsSubscription *sub, int64_t timeout)
	Blocks until the drain operation completes.
NATS_EXTERN natsStatus	natsSubscription_DrainCompletionStatus (natsSubscription *sub)
	Returns the status of the drain after completion.
NATS_EXTERN natsStatus	natsSubscription_SetOnCompleteCB (natsSubscription *sub, natsOnCompleteCB cb, void *closure)
	Sets a completion callback.
NATS_EXTERN void	natsSubscription_Destroy (natsSubscription *sub)
	Destroys the subscription.

Detailed Description

NATS Subscriptions.

Function Documentation

natsSubscription_NoDeliveryDelay()

NATS_EXTERN natsStatus natsSubscription_NoDeliveryDelay

(

natsSubscription *

sub

)

By default, messages that arrive are not immediately delivered. This generally improves performance. However, in case of request-reply, this delay has a negative impact. In such case, call this function to have the subscriber be notified immediately each time a message arrives.

Parameters

sub	the pointer to the natsSubscription object.

Deprecated

No longer needed. Will be removed in the future.

natsSubscription_NextMsg()

NATS_EXTERN natsStatus natsSubscription_NextMsg	(	natsMsg **	nextMsg,
		natsSubscription *	sub,
		int64_t	timeout )

Return the next message available to a synchronous subscriber or block until one is available. A timeout (expressed in milliseconds) can be used to return when no message has been delivered. If the value is zero, then this call will not wait and return the next message that was pending in the client, and NATS_TIMEOUT otherwise.

Note

If you create a subscription for a subject used as the reply subject of a natsConnection_PublishRequest call (or any of its variant), and there are no responders for the request subject, NATS Servers v2.2.0+ will return an empty message with a header "Status" and value "503". The library v2.2.0 until v2.4.1 would return this message to the user, which was wrong.
The library now returns no message and NATS_NO_RESPONDERS status.

Parameters

nextMsg	the location where to store the pointer to the next available message.
sub	the pointer to the natsSubscription object.
timeout	time, in milliseconds, after which this call will return NATS_TIMEOUT if no message is available.

natsSubscription_Unsubscribe()

NATS_EXTERN natsStatus natsSubscription_Unsubscribe

(

natsSubscription *

sub

)

Removes interest on the subject. Asynchronous subscription may still have a callback in progress, in that case, the subscription will still be valid until the callback returns.

Parameters

sub	the pointer to the natsSubscription object.

natsSubscription_AutoUnsubscribe()

NATS_EXTERN natsStatus natsSubscription_AutoUnsubscribe	(	natsSubscription *	sub,
		int	max )

This call issues an automatic natsSubscription_Unsubscribe that is processed by the server when 'max' messages have been received. This can be useful when sending a request to an unknown number of subscribers.

Parameters

sub	the pointer to the natsSubscription object.
max	the maximum number of message you want this subscription to receive.

natsSubscription_QueuedMsgs()

NATS_EXTERN natsStatus natsSubscription_QueuedMsgs	(	natsSubscription *	sub,
		uint64_t *	queuedMsgs )

Returns the number of queued messages in the client for this subscription.

Deprecated

Use natsSubscription_GetPending instead.

Parameters

sub	the pointer to the natsSubscription object.
queuedMsgs	the location where to store the number of queued messages.

natsSubscription_GetID()

NATS_EXTERN int64_t natsSubscription_GetID

(

natsSubscription *

sub

)

Returns the id of the given subscription.

Note

Invalid or closed subscriptions will cause a value of 0 to be returned.

Parameters

sub	the pointer to the natsSubscription object.

natsSubscription_GetSubject()

NATS_EXTERN const char * natsSubscription_GetSubject

(

natsSubscription *

sub

)

Returns the subject of the given subscription.

Note

Invalid or closed subscriptions will cause a value of NULL to be returned.

Warning

The string belongs to the subscription and must not be freed. Copy it if needed.

Parameters

sub	the pointer to the natsSubscription object.

natsSubscription_SetPendingLimits()

NATS_EXTERN natsStatus natsSubscription_SetPendingLimits	(	natsSubscription *	sub,
		int	msgLimit,
		int	bytesLimit )

Specifies the maximum number and size of incoming messages that can be buffered in the library for this subscription, before new incoming messages are dropped and NATS_SLOW_CONSUMER status is reported to the natsErrHandler callback (if one has been set).

If no limit is set at the subscription level, the limit set by natsOptions_SetMaxPendingMsgs before creating the connection will be used.

Note

If no option is set, there is still a default of 65536 messages and 65536 * 1024 bytes.

See also

natsOptions_SetMaxPendingMsgs

natsSubscription_GetPendingLimits

Parameters

sub	he pointer to the natsSubscription object.
msgLimit	the limit in number of messages that the subscription can hold.
bytesLimit	the limit in bytes that the subscription can hold.

natsSubscription_GetPendingLimits()

NATS_EXTERN natsStatus natsSubscription_GetPendingLimits	(	natsSubscription *	sub,
		int *	msgLimit,
		int *	bytesLimit )

Regardless if limits have been explicitly set with natsSubscription_SetPendingLimits, this call will store in the provided memory locations, the limits set for this subscription.

Note

It is possible for msgLimit and/or bytesLimits to be NULL, in which case the corresponding value is obviously not stored, but the function will not return an error.

See also

natsOptions_SetMaxPendingMsgs

natsSubscription_SetPendingLimits

Parameters

sub	the pointer to the natsSubscription object.
msgLimit	if not NULL, the memory location where to store the maximum number of pending messages for this subscription.
bytesLimit	if not NULL, the memory location where to store the maximum size of pending messages for this subscription.

natsSubscription_GetPending()

NATS_EXTERN natsStatus natsSubscription_GetPending	(	natsSubscription *	sub,
		int *	msgs,
		int *	bytes )

Returns the total number and size of pending messages on this subscription.

Note

It is possible for msgs and bytes to be NULL, in which case the corresponding values are obviously not stored, but the function will not return an error.

Parameters

sub	the pointer to the natsSubscription object.
msgs	if not NULL, the memory location where to store the number of pending messages.
bytes	if not NULL, the memory location where to store the total size of pending messages.

natsSubscription_GetDelivered()

NATS_EXTERN natsStatus natsSubscription_GetDelivered	(	natsSubscription *	sub,
		int64_t *	msgs )

Returns the number of delivered messages for this subscription.

Parameters

sub	the pointer to the natsSubscription object.
msgs	the memory location where to store the number of delivered messages.

natsSubscription_GetDropped()

NATS_EXTERN natsStatus natsSubscription_GetDropped	(	natsSubscription *	sub,
		int64_t *	msgs )

Returns the number of known dropped messages for this subscription. This happens when a consumer is not keeping up and the library starts to drop messages when the maximum number (and/or size) of pending messages has been reached.

Note

If the server declares the connection a slow consumer, this number may not be valid.

See also

natsOptions_SetMaxPendingMsgs

natsSubscription_SetPendingLimits

Parameters

sub	the pointer to the natsSubscription object.
msgs	the memory location where to store the number of dropped messages.

natsSubscription_GetMaxPending()

NATS_EXTERN natsStatus natsSubscription_GetMaxPending	(	natsSubscription *	sub,
		int *	msgs,
		int *	bytes )

Returns the maximum of pending messages and bytes seen so far.

Note

msgs and/or bytes can be NULL.

Parameters

sub	the pointer to the natsSubscription object.
msgs	if not NULL, the memory location where to store the maximum number of pending messages seen so far.
bytes	if not NULL, the memory location where to store the maximum number of bytes pending seen so far.

natsSubscription_ClearMaxPending()

NATS_EXTERN natsStatus natsSubscription_ClearMaxPending

(

natsSubscription *

sub

)

Clears the statistics regarding the maximum pending values.

Parameters

sub	the pointer to the natsSubscription object.

natsSubscription_GetStats()

NATS_EXTERN natsStatus natsSubscription_GetStats	(	natsSubscription *	sub,
		int *	pendingMsgs,
		int *	pendingBytes,
		int *	maxPendingMsgs,
		int *	maxPendingBytes,
		int64_t *	deliveredMsgs,
		int64_t *	droppedMsgs )

This is a convenient function to get several subscription's statistics in one call.

Note

Any or all of the statistics pointers can be NULL.

See also

natsSubscription_GetPending

natsSubscription_GetMaxPending

natsSubscription_GetDelivered

natsSubscription_GetDropped

Parameters

sub	the pointer to the natsSubscription object.
pendingMsgs	if not NULL, memory location where to store the number of pending messages.
pendingBytes	if not NULL, memory location where to store the total size of pending messages.
maxPendingMsgs	if not NULL, memory location where to store the maximum number of pending messages seen so far.
maxPendingBytes	if not NULL, memory location where to store the maximum total size of pending messages seen so far.
deliveredMsgs	if not NULL, memory location where to store the number of delivered messages.
droppedMsgs	if not NULL, memory location where to store the number of dropped messages.

natsSubscription_IsValid()

NATS_EXTERN bool natsSubscription_IsValid

(

natsSubscription *

sub

)

Returns a boolean indicating whether the subscription is still active. This will return false if the subscription has already been closed, or auto unsubscribed.

Parameters

sub	the pointer to the natsSubscription object.

natsSubscription_Drain()

NATS_EXTERN natsStatus natsSubscription_Drain

(

natsSubscription *

sub

)

Drain will remove interest but continue to invoke callbacks until all messages have been processed.

This call uses a default drain timeout of 30 seconds. See natsSubscription_DrainTimeout for details on behavior when timeout elapses.

Warning

This function does not block waiting for the operation to complete. To synchronously wait, see natsSubscription_WaitForDrainCompletion

See also

natsSubscription_DrainTimeout

natsSubscription_WaitForDrainCompletion

natsSubscription_DrainCompletionStatus

Parameters

sub	the pointer to the natsSubscription object.

natsSubscription_DrainTimeout()

NATS_EXTERN natsStatus natsSubscription_DrainTimeout	(	natsSubscription *	sub,
		int64_t	timeout )

Drain will remove interest but continue to invoke callbacks until all messages have been processed, or the specified timeout has elapsed. In that case, the subscription will be forcibly closed and remaining pending messages (if any) will not be processed.

The timeout is expressed in milliseconds. Zero or negative value means that the call will not timeout, but see below for more details.

When this call returns, the UNSUBSCRIBE protocol for this subscription has been enqueued to the outgoing connection buffer, but not sent to the server, ensuring that this call does not block.

The library then asynchronously ensures that this protocol is sent and waits for a confirmation from the server. After that, it is guaranteed that no new message for this subscription will be received and the library can proceed with the rest of the draining.

However, should the "flush" of the protocol fail, the library will ensure that no new message is added to the subscription (in the event the server did not receive the UNSUBSCRIBE protocol and still attempts to deliver messages), and will proceed with the draining of the pending messages. Users can check the status of the draining after it has completed by calling natsSubscription_DrainCompletionStatus.

If no timeout is specified (that is, value is zero or negative), a timeout will be used for the "flush" of the protocol. Again, even in case of failure, the draining will proceed.

If a timeout is specified, the complete process: "flush" of the protocol and draining of messages, must happen before the timeout elapses otherwise the subscription will be forcibly closed, and not all message callbacks may be invoked.

Regardless of the presence of a timeout or not, should the subscription or connection be closed while draining occurs, the draining process will stop. The natsSubscription_WaitForDrainCompletion call will not report an error. To know if an error occurred, the user can call natsSubscription_DrainCompletionStatus after ensuring that the drain has completed.

Warning

This function does not block waiting for the operation to complete. To synchronously wait, see natsSubscription_WaitForDrainCompletion

See also

natsSubscription_Drain

natsSubscription_WaitForDrainCompletion

natsSubscription_DrainCompletionStatus

Parameters

sub	the pointer to the natsSubscription object.
timeout	how long to wait for the operation to complete, expressed in milliseconds. If the timeout elapses the subscription will be closed.

natsSubscription_WaitForDrainCompletion()

NATS_EXTERN natsStatus natsSubscription_WaitForDrainCompletion	(	natsSubscription *	sub,
		int64_t	timeout )

This function blocks until the subscription is fully drained. Returns no error if the subscription is drained or closed, otherwise returns the error if the subscription was not in drained mode (NATS_ILLEGAL_STATE) or if this subscription was not drained or closed prior to the specified timeout (NATS_TIMEOUT).

The timeout is expressed in milliseconds. Zero or negative value means that the call will not timeout.

Note that if this call times-out, it does not mean that the drain stops. The drain will continue until its own timeout elapses.

See also

natsSubscription_Drain

natsSubscription_DrainTimeout

natsSubscription_DrainCompletionStatus

Parameters

sub	the pointer to the natsSubscription object.
timeout	how long to wait for the operation to complete, expressed in milliseconds.

natsSubscription_DrainCompletionStatus()

NATS_EXTERN natsStatus natsSubscription_DrainCompletionStatus

(

natsSubscription *

sub

)

Once the drain has completed, users can use this function to know if the drain completed successfully or not.

Possible return values (the list is not exhaustive):

NATS_OK the library sent the UNSUBSCRIBE protocol and finished processing all messages that were pending.
NATS_ILLEGAL_STATE this call was made for a subscription that had not started draining or the draining is still in progress.
NATS_INVALID_SUBSCRIPTION the subscription was closed while draining, which means that some messages may not have been processed.
NATS_CONNECTION_CLOSED the connection was closed while draining, which means that some messages may not have been processed.

Note

This call does not wait for the drain completion (see natsSubscription_WaitForDrainCompletion for that).

See also

natsSubscription_Drain

natsSubscription_DrainTimeout

natsSubscription_WaitForDrainCompletion

Parameters

sub	the pointer to the natsSubscription object.

natsSubscription_SetOnCompleteCB()

NATS_EXTERN natsStatus natsSubscription_SetOnCompleteCB	(	natsSubscription *	sub,
		natsOnCompleteCB	cb,
		void *	closure )

In order to make sure that an asynchronous subscription's message handler is no longer invoked once the subscription is closed (natsSubscription_Unsubscribe), the subscription should be closed from the message handler itslef.

If the application closes the subscription from a different thread and immediately frees resources needed in the message handler, there is a risk of a crash since the subscription's message handler may still be invoked one last time or already in the process of executing.

To address this, the user can set a callback that will be invoked after the subscription is closed and the message handler has returned. This applies to asynchronous subscriptions using their own dispatcher or using the library's delivery thread pool.

Note

You don't need to call this function if you are not freeing resources needed in the message handler or if you always close the subscription from the message handler itself.

If you plan on calling this function, you should do so before calling natsSubscription_AutoUnsubscribe, since there is a risk that the subscription be removed as soon as natsSubscription_AutoUnsubscribe returns.

Calling this function on a synchronous or closed subscription will return NATS_INVALID_SUBSCRIPTION.

See also

natsOnCompleteCB

Parameters

sub	the pointer to the natsSubscription object
cb	the callback to invoke when the last message of a closed subscription has been dispatched
closure	the pointer to a user defined object (possibly NULL) that will be passed to the callback

natsSubscription_Destroy()

NATS_EXTERN void natsSubscription_Destroy

(

natsSubscription *

sub

)

Destroys the subscription object, freeing up memory. If not already done, this call will removes interest on the subject.

Parameters

sub	the pointer to the natsSubscription object to destroy.