Streaming Subscription

Functions
NATS_EXTERN natsStatus	stanSubscription_SetOnCompleteCB (stanSubscription *sub, natsOnCompleteCB cb, void *closure)
	Sets a completion callback.
NATS_EXTERN natsStatus	stanSubscription_AckMsg (stanSubscription *sub, stanMsg *msg)
	Acknowledge a message.
NATS_EXTERN natsStatus	stanSubscription_Unsubscribe (stanSubscription *sub)
	Permanently remove a subscription.
NATS_EXTERN natsStatus	stanSubscription_Close (stanSubscription *sub)
	Closes the subscription.
NATS_EXTERN void	stanSubscription_Destroy (stanSubscription *sub)
	Destroys the subscription.

Detailed Description

NATS Streaming Subscriptions.

Function Documentation

stanSubscription_SetOnCompleteCB()

NATS_EXTERN natsStatus stanSubscription_SetOnCompleteCB	(	stanSubscription *	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 (or unsubscribed) (stanSubscription_Close, stanSubscription_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.

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.

See also

natsOnCompleteCB

Parameters

sub	the pointer to the stanSubscription 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

stanSubscription_AckMsg()

NATS_EXTERN natsStatus stanSubscription_AckMsg	(	stanSubscription *	sub,
		stanMsg *	msg )

If the subscription is created with manual acknowledgment mode (see stanSubOptions_SetManualAckMode) then it is the user responsibility to acknowledge received messages when appropriate.

Parameters

sub	the pointer to the stanSubscription object.
msg	the message to acknowledge.

stanSubscription_Unsubscribe()

NATS_EXTERN natsStatus stanSubscription_Unsubscribe

(

stanSubscription *

sub

)

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

For non-durable subscriptions, stanSubscription_Unsubscribe and stanSubscription_Close have the same effect.

For durable subscriptions, calling this function causes the server to remove the durable subscription (instead of simply suspending it). It means that once this call is made, calling stanConnection_Subscribe() with the same durable name creates a brand new durable subscription, instead of simply resuming delivery.

Warning

See warning about connecting to a NATS Server v2.2.0+ in stanConnection_Connect().

Parameters

sub	the pointer to the stanSubscription object.

stanSubscription_Close()

NATS_EXTERN natsStatus stanSubscription_Close

(

stanSubscription *

sub

)

Similar to stanSubscription_Unsubscribe() except that durable interest is not removed in the server. The durable subscription can therefore be resumed.

Warning

See warning about connecting to a NATS Server v2.2.0+ in stanConnection_Connect().

Parameters

sub	the pointer to the stanSubscription object.

stanSubscription_Destroy()

NATS_EXTERN void stanSubscription_Destroy

(

stanSubscription *

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 stanSubscription object to destroy.