<trclass="memdesc:ga38f1e41fc7619101fc4aa52014dd5428"><tdclass="mdescLeft"> </td><tdclass="mdescRight">Enables the No Delivery Delay mode. <br/></td></tr>
<trclass="memdesc:ga6538a5d78dfb0f16514b94c8e74c11af"><tdclass="mdescLeft"> </td><tdclass="mdescRight">Returns the next available message. <br/></td></tr>
<trclass="memitem:ga09f285de2746a6e27fc66efd60bd3116"id="r_ga09f285de2746a6e27fc66efd60bd3116"><tdclass="memItemLeft"align="right"valign="top"><aclass="el"href="nats_8h.html#a3bc1b3fe7f64083e60c7c3b93f205bad">NATS_EXTERN</a><aclass="el"href="status_8h.html#a36c934157b663b7b5fb5d6609c897c80">natsStatus</a> </td><tdclass="memItemRight"valign="bottom"><aclass="el"href="group__sub_group.html#ga09f285de2746a6e27fc66efd60bd3116">natsSubscription_AutoUnsubscribe</a> (<aclass="el"href="group__types_group.html#ga87158ec63b4f90f69e20451624ea01d8">natsSubscription</a> *sub, int max)</td></tr>
<trclass="memdesc:ga8a37b2d5290da3aecc05483d79e7e254"><tdclass="mdescLeft"> </td><tdclass="mdescRight">Gets the number of pending messages. <br/></td></tr>
<trclass="memitem:ga68a7cea89e75c529a7dd3bb77303dda4"id="r_ga68a7cea89e75c529a7dd3bb77303dda4"><tdclass="memItemLeft"align="right"valign="top"><aclass="el"href="nats_8h.html#a3bc1b3fe7f64083e60c7c3b93f205bad">NATS_EXTERN</a><aclass="el"href="status_8h.html#a36c934157b663b7b5fb5d6609c897c80">natsStatus</a> </td><tdclass="memItemRight"valign="bottom"><aclass="el"href="group__sub_group.html#ga68a7cea89e75c529a7dd3bb77303dda4">natsSubscription_SetPendingLimits</a> (<aclass="el"href="group__types_group.html#ga87158ec63b4f90f69e20451624ea01d8">natsSubscription</a> *sub, int msgLimit, int bytesLimit)</td></tr>
<trclass="memdesc:ga68a7cea89e75c529a7dd3bb77303dda4"><tdclass="mdescLeft"> </td><tdclass="mdescRight">Sets the limit for pending messages and bytes. <br/></td></tr>
<trclass="memitem:ga786bb458981274fe717f266bd3b96d96"id="r_ga786bb458981274fe717f266bd3b96d96"><tdclass="memItemLeft"align="right"valign="top"><aclass="el"href="nats_8h.html#a3bc1b3fe7f64083e60c7c3b93f205bad">NATS_EXTERN</a><aclass="el"href="status_8h.html#a36c934157b663b7b5fb5d6609c897c80">natsStatus</a> </td><tdclass="memItemRight"valign="bottom"><aclass="el"href="group__sub_group.html#ga786bb458981274fe717f266bd3b96d96">natsSubscription_GetPendingLimits</a> (<aclass="el"href="group__types_group.html#ga87158ec63b4f90f69e20451624ea01d8">natsSubscription</a> *sub, int *msgLimit, int *bytesLimit)</td></tr>
<trclass="memdesc:ga786bb458981274fe717f266bd3b96d96"><tdclass="mdescLeft"> </td><tdclass="mdescRight">Returns the current limit for pending messages and bytes. <br/></td></tr>
<trclass="memitem:gaca6262e2ef842caa701a9f233db72707"id="r_gaca6262e2ef842caa701a9f233db72707"><tdclass="memItemLeft"align="right"valign="top"><aclass="el"href="nats_8h.html#a3bc1b3fe7f64083e60c7c3b93f205bad">NATS_EXTERN</a><aclass="el"href="status_8h.html#a36c934157b663b7b5fb5d6609c897c80">natsStatus</a> </td><tdclass="memItemRight"valign="bottom"><aclass="el"href="group__sub_group.html#gaca6262e2ef842caa701a9f233db72707">natsSubscription_GetPending</a> (<aclass="el"href="group__types_group.html#ga87158ec63b4f90f69e20451624ea01d8">natsSubscription</a> *sub, int *msgs, int *bytes)</td></tr>
<trclass="memdesc:gaca6262e2ef842caa701a9f233db72707"><tdclass="mdescLeft"> </td><tdclass="mdescRight">Returns the number of pending messages and bytes. <br/></td></tr>
<trclass="memdesc:ga476b7276d0b7f9946834d2bb2423e955"><tdclass="mdescLeft"> </td><tdclass="mdescRight">Returns the number of delivered messages. <br/></td></tr>
<trclass="memdesc:ga24f1636869e26661ce62c9c9f4d80823"><tdclass="mdescLeft"> </td><tdclass="mdescRight">Returns the number of dropped messages. <br/></td></tr>
<trclass="memitem:ga0abc5d9afbc6b0c9c5adaf533904c968"id="r_ga0abc5d9afbc6b0c9c5adaf533904c968"><tdclass="memItemLeft"align="right"valign="top"><aclass="el"href="nats_8h.html#a3bc1b3fe7f64083e60c7c3b93f205bad">NATS_EXTERN</a><aclass="el"href="status_8h.html#a36c934157b663b7b5fb5d6609c897c80">natsStatus</a> </td><tdclass="memItemRight"valign="bottom"><aclass="el"href="group__sub_group.html#ga0abc5d9afbc6b0c9c5adaf533904c968">natsSubscription_GetMaxPending</a> (<aclass="el"href="group__types_group.html#ga87158ec63b4f90f69e20451624ea01d8">natsSubscription</a> *sub, int *msgs, int *bytes)</td></tr>
<trclass="memdesc:ga0abc5d9afbc6b0c9c5adaf533904c968"><tdclass="mdescLeft"> </td><tdclass="mdescRight">Returns the maximum number of pending messages and bytes. <br/></td></tr>
<trclass="memdesc:gafe31911d8372db401d33856465421710"><tdclass="mdescLeft"> </td><tdclass="mdescRight">Clears the statistics regarding the maximum pending values. <br/></td></tr>
<trclass="memitem:ga12b60cdb3aca7329edebc480ae86bfab"id="r_ga12b60cdb3aca7329edebc480ae86bfab"><tdclass="memItemLeft"align="right"valign="top"><aclass="el"href="nats_8h.html#a3bc1b3fe7f64083e60c7c3b93f205bad">NATS_EXTERN</a><aclass="el"href="status_8h.html#a36c934157b663b7b5fb5d6609c897c80">natsStatus</a> </td><tdclass="memItemRight"valign="bottom"><aclass="el"href="group__sub_group.html#ga12b60cdb3aca7329edebc480ae86bfab">natsSubscription_GetStats</a> (<aclass="el"href="group__types_group.html#ga87158ec63b4f90f69e20451624ea01d8">natsSubscription</a> *sub, int *pendingMsgs, int *pendingBytes, int *maxPendingMsgs, int *maxPendingBytes, int64_t *deliveredMsgs, int64_t *droppedMsgs)</td></tr>
<trclass="memdesc:ga12b60cdb3aca7329edebc480ae86bfab"><tdclass="mdescLeft"> </td><tdclass="mdescRight">Get various statistics from this subscription. <br/></td></tr>
<trclass="memdesc:ga5e6454bbc7a90b9694112d45bd8de903"><tdclass="mdescLeft"> </td><tdclass="mdescRight">Checks the validity of the subscription. <br/></td></tr>
<trclass="memdesc:ga26c9736289d326fb7d6df7e2a0df72ab"><tdclass="mdescLeft"> </td><tdclass="mdescRight">Drains the subscription with a default timeout. <br/></td></tr>
<trclass="memdesc:ga9c26a3f9584e7804060a48ec1b7e2a68"><tdclass="mdescLeft"> </td><tdclass="mdescRight">Drains the subscription with the specified timeout. <br/></td></tr>
<trclass="memdesc:ga0408c9b6e4ad4078ac0267656ace222d"><tdclass="mdescLeft"> </td><tdclass="mdescRight">Blocks until the drain operation completes. <br/></td></tr>
<trclass="memdesc:ga9834bd02f67a25ac084d5ad71e146019"><tdclass="mdescLeft"> </td><tdclass="mdescRight">Returns the status of the drain after completion. <br/></td></tr>
<trclass="memdesc:gaea632f845d473e7461b134c0e7bf4077"><tdclass="mdescLeft"> </td><tdclass="mdescRight">Sets a completion callback. <br/></td></tr>
<p>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.</p>
<dlclass="params"><dt>Parameters</dt><dd>
<tableclass="params">
<tr><tdclass="paramname">sub</td><td>the pointer to the <aclass="el"href="group__types_group.html#ga87158ec63b4f90f69e20451624ea01d8"title="Interest on a given subject.">natsSubscription</a> object.</td></tr>
</table>
</dd>
</dl>
<dlclass="deprecated"><dt><b><aclass="el"href="deprecated.html#_deprecated000001">Deprecated:</a></b></dt><dd>No longer needed. Will be removed in the future. </dd></dl>
<p>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 <aclass="el"href="status_8h.html#a36c934157b663b7b5fb5d6609c897c80ab88994c9ea9889ac4d9d656d62f550ed">NATS_TIMEOUT</a> otherwise.</p>
<dlclass="section note"><dt>Note</dt><dd>If you create a subscription for a subject used as the reply subject of a <aclass="el"href="group__conn_pub_group.html#gaaaa3d75ffec2dcdc6bf905cdb1eee59e"title="Publishes data on a subject expecting replies on the given reply.">natsConnection_PublishRequest</a> 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.<br/>
The library now returns no message and <aclass="el"href="status_8h.html#a36c934157b663b7b5fb5d6609c897c80aab97324e40ccfe1360080c651c330e62"title="No responders were running when the server received the request.">NATS_NO_RESPONDERS</a> status.</dd></dl>
<dlclass="params"><dt>Parameters</dt><dd>
<tableclass="params">
<tr><tdclass="paramname">nextMsg</td><td>the location where to store the pointer to the next available message. </td></tr>
<tr><tdclass="paramname">sub</td><td>the pointer to the <aclass="el"href="group__types_group.html#ga87158ec63b4f90f69e20451624ea01d8"title="Interest on a given subject.">natsSubscription</a> object. </td></tr>
<tr><tdclass="paramname">timeout</td><td>time, in milliseconds, after which this call will return <aclass="el"href="status_8h.html#a36c934157b663b7b5fb5d6609c897c80ab88994c9ea9889ac4d9d656d62f550ed">NATS_TIMEOUT</a> if no message is available. </td></tr>
<p>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.</p>
<dlclass="params"><dt>Parameters</dt><dd>
<tableclass="params">
<tr><tdclass="paramname">sub</td><td>the pointer to the <aclass="el"href="group__types_group.html#ga87158ec63b4f90f69e20451624ea01d8"title="Interest on a given subject.">natsSubscription</a> object. </td></tr>
<p>This call issues an automatic <aclass="el"href="group__sub_group.html#gaee87f8be0e6c2a4693ba2cea070583ba"title="Unsubscribes.">natsSubscription_Unsubscribe</a> 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.</p>
<dlclass="params"><dt>Parameters</dt><dd>
<tableclass="params">
<tr><tdclass="paramname">sub</td><td>the pointer to the <aclass="el"href="group__types_group.html#ga87158ec63b4f90f69e20451624ea01d8"title="Interest on a given subject.">natsSubscription</a> object. </td></tr>
<tr><tdclass="paramname">max</td><td>the maximum number of message you want this subscription to receive. </td></tr>
<p>Returns the number of queued messages in the client for this subscription.</p>
<dlclass="deprecated"><dt><b><aclass="el"href="deprecated.html#_deprecated000002">Deprecated:</a></b></dt><dd>Use <aclass="el"href="group__sub_group.html#gaca6262e2ef842caa701a9f233db72707"title="Returns the number of pending messages and bytes.">natsSubscription_GetPending</a> instead.</dd></dl>
<dlclass="params"><dt>Parameters</dt><dd>
<tableclass="params">
<tr><tdclass="paramname">sub</td><td>the pointer to the <aclass="el"href="group__types_group.html#ga87158ec63b4f90f69e20451624ea01d8"title="Interest on a given subject.">natsSubscription</a> object. </td></tr>
<tr><tdclass="paramname">queuedMsgs</td><td>the location where to store the number of queued messages. </td></tr>
<dlclass="section note"><dt>Note</dt><dd>Invalid or closed subscriptions will cause a value of 0 to be returned.</dd></dl>
<dlclass="params"><dt>Parameters</dt><dd>
<tableclass="params">
<tr><tdclass="paramname">sub</td><td>the pointer to the <aclass="el"href="group__types_group.html#ga87158ec63b4f90f69e20451624ea01d8"title="Interest on a given subject.">natsSubscription</a> object. </td></tr>
<p>Returns the subject of the given subscription.</p>
<dlclass="section note"><dt>Note</dt><dd>Invalid or closed subscriptions will cause a value of NULL to be returned.</dd></dl>
<dlclass="section warning"><dt>Warning</dt><dd>The string belongs to the subscription and must not be freed. Copy it if needed.</dd></dl>
<dlclass="params"><dt>Parameters</dt><dd>
<tableclass="params">
<tr><tdclass="paramname">sub</td><td>the pointer to the <aclass="el"href="group__types_group.html#ga87158ec63b4f90f69e20451624ea01d8"title="Interest on a given subject.">natsSubscription</a> object. </td></tr>
<p>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 <aclass="el"href="status_8h.html#a36c934157b663b7b5fb5d6609c897c80ae93ff5b7fe31f8570308385d92d317b0">NATS_SLOW_CONSUMER</a> status is reported to the <aclass="el"href="group__callbacks_group.html#ga9e511dffa471dfb971b7dd2b12329626"title="Callback used to notify the user of errors encountered while processing inbound messages.">natsErrHandler</a> callback (if one has been set).</p>
<p>If no limit is set at the subscription level, the limit set by <aclass="el"href="group__opts_group.html#ga95510436eee06f9992ded96a44795c40"title="Sets the maximum number of pending messages per subscription.">natsOptions_SetMaxPendingMsgs</a> before creating the connection will be used.</p>
<dlclass="section note"><dt>Note</dt><dd>If no option is set, there is still a default of <code>65536</code> messages and <code>65536 * 1024</code> bytes.</dd></dl>
<dlclass="section see"><dt>See also</dt><dd><aclass="el"href="group__opts_group.html#ga95510436eee06f9992ded96a44795c40"title="Sets the maximum number of pending messages per subscription.">natsOptions_SetMaxPendingMsgs</a></dd>
<dd>
<aclass="el"href="group__sub_group.html#ga786bb458981274fe717f266bd3b96d96"title="Returns the current limit for pending messages and bytes.">natsSubscription_GetPendingLimits</a></dd></dl>
<dlclass="params"><dt>Parameters</dt><dd>
<tableclass="params">
<tr><tdclass="paramname">sub</td><td>he pointer to the <aclass="el"href="group__types_group.html#ga87158ec63b4f90f69e20451624ea01d8"title="Interest on a given subject.">natsSubscription</a> object. </td></tr>
<tr><tdclass="paramname">msgLimit</td><td>the limit in number of messages that the subscription can hold. </td></tr>
<tr><tdclass="paramname">bytesLimit</td><td>the limit in bytes that the subscription can hold. </td></tr>
<p>Regardless if limits have been explicitly set with <aclass="el"href="group__sub_group.html#ga68a7cea89e75c529a7dd3bb77303dda4"title="Sets the limit for pending messages and bytes.">natsSubscription_SetPendingLimits</a>, this call will store in the provided memory locations, the limits set for this subscription.</p>
<dlclass="section note"><dt>Note</dt><dd>It is possible for <code>msgLimit</code> and/or <code>bytesLimits</code> to be <code>NULL</code>, in which case the corresponding value is obviously not stored, but the function will not return an error.</dd></dl>
<dlclass="section see"><dt>See also</dt><dd><aclass="el"href="group__opts_group.html#ga95510436eee06f9992ded96a44795c40"title="Sets the maximum number of pending messages per subscription.">natsOptions_SetMaxPendingMsgs</a></dd>
<dd>
<aclass="el"href="group__sub_group.html#ga68a7cea89e75c529a7dd3bb77303dda4"title="Sets the limit for pending messages and bytes.">natsSubscription_SetPendingLimits</a></dd></dl>
<dlclass="params"><dt>Parameters</dt><dd>
<tableclass="params">
<tr><tdclass="paramname">sub</td><td>the pointer to the <aclass="el"href="group__types_group.html#ga87158ec63b4f90f69e20451624ea01d8"title="Interest on a given subject.">natsSubscription</a> object. </td></tr>
<tr><tdclass="paramname">msgLimit</td><td>if not <code>NULL</code>, the memory location where to store the maximum number of pending messages for this subscription. </td></tr>
<tr><tdclass="paramname">bytesLimit</td><td>if not <code>NULL</code>, the memory location where to store the maximum size of pending messages for this subscription. </td></tr>
<p>Returns the total number and size of pending messages on this subscription.</p>
<dlclass="section note"><dt>Note</dt><dd>It is possible for <code>msgs</code> and <code>bytes</code> to be NULL, in which case the corresponding values are obviously not stored, but the function will not return an error.</dd></dl>
<dlclass="params"><dt>Parameters</dt><dd>
<tableclass="params">
<tr><tdclass="paramname">sub</td><td>the pointer to the <aclass="el"href="group__types_group.html#ga87158ec63b4f90f69e20451624ea01d8"title="Interest on a given subject.">natsSubscription</a> object. </td></tr>
<tr><tdclass="paramname">msgs</td><td>if not <code>NULL</code>, the memory location where to store the number of pending messages. </td></tr>
<tr><tdclass="paramname">bytes</td><td>if not <code>NULL</code>, the memory location where to store the total size of pending messages. </td></tr>
<p>Returns the number of delivered messages for this subscription.</p>
<dlclass="params"><dt>Parameters</dt><dd>
<tableclass="params">
<tr><tdclass="paramname">sub</td><td>the pointer to the <aclass="el"href="group__types_group.html#ga87158ec63b4f90f69e20451624ea01d8"title="Interest on a given subject.">natsSubscription</a> object. </td></tr>
<tr><tdclass="paramname">msgs</td><td>the memory location where to store the number of delivered messages. </td></tr>
<p>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.</p>
<dlclass="section note"><dt>Note</dt><dd>If the server declares the connection a slow consumer, this number may not be valid.</dd></dl>
<dlclass="section see"><dt>See also</dt><dd><aclass="el"href="group__opts_group.html#ga95510436eee06f9992ded96a44795c40"title="Sets the maximum number of pending messages per subscription.">natsOptions_SetMaxPendingMsgs</a></dd>
<dd>
<aclass="el"href="group__sub_group.html#ga68a7cea89e75c529a7dd3bb77303dda4"title="Sets the limit for pending messages and bytes.">natsSubscription_SetPendingLimits</a></dd></dl>
<dlclass="params"><dt>Parameters</dt><dd>
<tableclass="params">
<tr><tdclass="paramname">sub</td><td>the pointer to the <aclass="el"href="group__types_group.html#ga87158ec63b4f90f69e20451624ea01d8"title="Interest on a given subject.">natsSubscription</a> object. </td></tr>
<tr><tdclass="paramname">msgs</td><td>the memory location where to store the number of dropped messages. </td></tr>
<p>Returns the maximum of pending messages and bytes seen so far.</p>
<dlclass="section note"><dt>Note</dt><dd><code>msgs</code> and/or <code>bytes</code> can be NULL.</dd></dl>
<dlclass="params"><dt>Parameters</dt><dd>
<tableclass="params">
<tr><tdclass="paramname">sub</td><td>the pointer to the <aclass="el"href="group__types_group.html#ga87158ec63b4f90f69e20451624ea01d8"title="Interest on a given subject.">natsSubscription</a> object. </td></tr>
<tr><tdclass="paramname">msgs</td><td>if not <code>NULL</code>, the memory location where to store the maximum number of pending messages seen so far. </td></tr>
<tr><tdclass="paramname">bytes</td><td>if not <code>NULL</code>, the memory location where to store the maximum number of bytes pending seen so far. </td></tr>
<p>Clears the statistics regarding the maximum pending values.</p>
<dlclass="params"><dt>Parameters</dt><dd>
<tableclass="params">
<tr><tdclass="paramname">sub</td><td>the pointer to the <aclass="el"href="group__types_group.html#ga87158ec63b4f90f69e20451624ea01d8"title="Interest on a given subject.">natsSubscription</a> object. </td></tr>
<p>This is a convenient function to get several subscription's statistics in one call.</p>
<dlclass="section note"><dt>Note</dt><dd>Any or all of the statistics pointers can be <code>NULL</code>.</dd></dl>
<dlclass="section see"><dt>See also</dt><dd><aclass="el"href="group__sub_group.html#gaca6262e2ef842caa701a9f233db72707"title="Returns the number of pending messages and bytes.">natsSubscription_GetPending</a></dd>
<dd>
<aclass="el"href="group__sub_group.html#ga0abc5d9afbc6b0c9c5adaf533904c968"title="Returns the maximum number of pending messages and bytes.">natsSubscription_GetMaxPending</a></dd>
<dd>
<aclass="el"href="group__sub_group.html#ga476b7276d0b7f9946834d2bb2423e955"title="Returns the number of delivered messages.">natsSubscription_GetDelivered</a></dd>
<dd>
<aclass="el"href="group__sub_group.html#ga24f1636869e26661ce62c9c9f4d80823"title="Returns the number of dropped messages.">natsSubscription_GetDropped</a></dd></dl>
<dlclass="params"><dt>Parameters</dt><dd>
<tableclass="params">
<tr><tdclass="paramname">sub</td><td>the pointer to the <aclass="el"href="group__types_group.html#ga87158ec63b4f90f69e20451624ea01d8"title="Interest on a given subject.">natsSubscription</a> object. </td></tr>
<tr><tdclass="paramname">pendingMsgs</td><td>if not <code>NULL</code>, memory location where to store the number of pending messages. </td></tr>
<tr><tdclass="paramname">pendingBytes</td><td>if not <code>NULL</code>, memory location where to store the total size of pending messages. </td></tr>
<tr><tdclass="paramname">maxPendingMsgs</td><td>if not <code>NULL</code>, memory location where to store the maximum number of pending messages seen so far. </td></tr>
<tr><tdclass="paramname">maxPendingBytes</td><td>if not <code>NULL</code>, memory location where to store the maximum total size of pending messages seen so far. </td></tr>
<tr><tdclass="paramname">deliveredMsgs</td><td>if not <code>NULL</code>, memory location where to store the number of delivered messages. </td></tr>
<tr><tdclass="paramname">droppedMsgs</td><td>if not <code>NULL</code>, memory location where to store the number of dropped messages. </td></tr>
<p>Returns a boolean indicating whether the subscription is still active. This will return false if the subscription has already been closed, or auto unsubscribed.</p>
<dlclass="params"><dt>Parameters</dt><dd>
<tableclass="params">
<tr><tdclass="paramname">sub</td><td>the pointer to the <aclass="el"href="group__types_group.html#ga87158ec63b4f90f69e20451624ea01d8"title="Interest on a given subject.">natsSubscription</a> object. </td></tr>
<p>Drain will remove interest but continue to invoke callbacks until all messages have been processed.</p>
<p>This call uses a default drain timeout of 30 seconds. See <aclass="el"href="group__sub_group.html#ga9c26a3f9584e7804060a48ec1b7e2a68"title="Drains the subscription with the specified timeout.">natsSubscription_DrainTimeout</a> for details on behavior when timeout elapses.</p>
<dlclass="section warning"><dt>Warning</dt><dd>This function does not block waiting for the operation to complete. To synchronously wait, see <aclass="el"href="group__sub_group.html#ga0408c9b6e4ad4078ac0267656ace222d"title="Blocks until the drain operation completes.">natsSubscription_WaitForDrainCompletion</a></dd></dl>
<dlclass="section see"><dt>See also</dt><dd><aclass="el"href="group__sub_group.html#ga9c26a3f9584e7804060a48ec1b7e2a68"title="Drains the subscription with the specified timeout.">natsSubscription_DrainTimeout</a></dd>
<dd>
<aclass="el"href="group__sub_group.html#ga0408c9b6e4ad4078ac0267656ace222d"title="Blocks until the drain operation completes.">natsSubscription_WaitForDrainCompletion</a></dd>
<dd>
<aclass="el"href="group__sub_group.html#ga9834bd02f67a25ac084d5ad71e146019"title="Returns the status of the drain after completion.">natsSubscription_DrainCompletionStatus</a></dd></dl>
<dlclass="params"><dt>Parameters</dt><dd>
<tableclass="params">
<tr><tdclass="paramname">sub</td><td>the pointer to the <aclass="el"href="group__types_group.html#ga87158ec63b4f90f69e20451624ea01d8"title="Interest on a given subject.">natsSubscription</a> object. </td></tr>
<p>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.</p>
<p>The timeout is expressed in milliseconds. Zero or negative value means that the call will not timeout, but see below for more details.</p>
<p>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.</p>
<p>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.</p>
<p>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 <aclass="el"href="group__sub_group.html#ga9834bd02f67a25ac084d5ad71e146019"title="Returns the status of the drain after completion.">natsSubscription_DrainCompletionStatus</a>.</p>
<p>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.</p>
<p>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.</p>
<p>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 <aclass="el"href="group__sub_group.html#ga0408c9b6e4ad4078ac0267656ace222d"title="Blocks until the drain operation completes.">natsSubscription_WaitForDrainCompletion</a> call will not report an error. To know if an error occurred, the user can call <aclass="el"href="group__sub_group.html#ga9834bd02f67a25ac084d5ad71e146019"title="Returns the status of the drain after completion.">natsSubscription_DrainCompletionStatus</a> after ensuring that the drain has completed.</p>
<dlclass="section warning"><dt>Warning</dt><dd>This function does not block waiting for the operation to complete. To synchronously wait, see <aclass="el"href="group__sub_group.html#ga0408c9b6e4ad4078ac0267656ace222d"title="Blocks until the drain operation completes.">natsSubscription_WaitForDrainCompletion</a></dd></dl>
<dlclass="section see"><dt>See also</dt><dd><aclass="el"href="group__sub_group.html#ga26c9736289d326fb7d6df7e2a0df72ab"title="Drains the subscription with a default timeout.">natsSubscription_Drain</a></dd>
<dd>
<aclass="el"href="group__sub_group.html#ga0408c9b6e4ad4078ac0267656ace222d"title="Blocks until the drain operation completes.">natsSubscription_WaitForDrainCompletion</a></dd>
<dd>
<aclass="el"href="group__sub_group.html#ga9834bd02f67a25ac084d5ad71e146019"title="Returns the status of the drain after completion.">natsSubscription_DrainCompletionStatus</a></dd></dl>
<dlclass="params"><dt>Parameters</dt><dd>
<tableclass="params">
<tr><tdclass="paramname">sub</td><td>the pointer to the <aclass="el"href="group__types_group.html#ga87158ec63b4f90f69e20451624ea01d8"title="Interest on a given subject.">natsSubscription</a> object. </td></tr>
<tr><tdclass="paramname">timeout</td><td>how long to wait for the operation to complete, expressed in milliseconds. If the timeout elapses the subscription will be closed. </td></tr>
<p>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 (<aclass="el"href="status_8h.html#a36c934157b663b7b5fb5d6609c897c80a9bb78b4f245d2870040d25c450febd4b">NATS_ILLEGAL_STATE</a>) or if this subscription was not drained or closed prior to the specified timeout (<aclass="el"href="status_8h.html#a36c934157b663b7b5fb5d6609c897c80ab88994c9ea9889ac4d9d656d62f550ed">NATS_TIMEOUT</a>).</p>
<p>The timeout is expressed in milliseconds. Zero or negative value means that the call will not timeout.</p>
<p>Note that if this call times-out, it does not mean that the drain stops. The drain will continue until its own timeout elapses.</p>
<dlclass="section see"><dt>See also</dt><dd><aclass="el"href="group__sub_group.html#ga26c9736289d326fb7d6df7e2a0df72ab"title="Drains the subscription with a default timeout.">natsSubscription_Drain</a></dd>
<dd>
<aclass="el"href="group__sub_group.html#ga9c26a3f9584e7804060a48ec1b7e2a68"title="Drains the subscription with the specified timeout.">natsSubscription_DrainTimeout</a></dd>
<dd>
<aclass="el"href="group__sub_group.html#ga9834bd02f67a25ac084d5ad71e146019"title="Returns the status of the drain after completion.">natsSubscription_DrainCompletionStatus</a></dd></dl>
<dlclass="params"><dt>Parameters</dt><dd>
<tableclass="params">
<tr><tdclass="paramname">sub</td><td>the pointer to the <aclass="el"href="group__types_group.html#ga87158ec63b4f90f69e20451624ea01d8"title="Interest on a given subject.">natsSubscription</a> object. </td></tr>
<tr><tdclass="paramname">timeout</td><td>how long to wait for the operation to complete, expressed in milliseconds. </td></tr>
<p>Once the drain has completed, users can use this function to know if the drain completed successfully or not.</p>
<p>Possible return values (the list is not exhaustive):</p>
<p><code>NATS_OK</code> the library sent the UNSUBSCRIBE protocol and finished processing all messages that were pending.<br/>
<code>NATS_ILLEGAL_STATE</code> this call was made for a subscription that had not started draining or the draining is still in progress.<br/>
<code>NATS_INVALID_SUBSCRIPTION</code> the subscription was closed while draining, which means that some messages may not have been processed.<br/>
<code>NATS_CONNECTION_CLOSED</code> the connection was closed while draining, which means that some messages may not have been processed.</p>
<dlclass="section note"><dt>Note</dt><dd>This call does not wait for the drain completion (see <aclass="el"href="group__sub_group.html#ga0408c9b6e4ad4078ac0267656ace222d"title="Blocks until the drain operation completes.">natsSubscription_WaitForDrainCompletion</a> for that).</dd></dl>
<dlclass="section see"><dt>See also</dt><dd><aclass="el"href="group__sub_group.html#ga26c9736289d326fb7d6df7e2a0df72ab"title="Drains the subscription with a default timeout.">natsSubscription_Drain</a></dd>
<dd>
<aclass="el"href="group__sub_group.html#ga9c26a3f9584e7804060a48ec1b7e2a68"title="Drains the subscription with the specified timeout.">natsSubscription_DrainTimeout</a></dd>
<dd>
<aclass="el"href="group__sub_group.html#ga0408c9b6e4ad4078ac0267656ace222d"title="Blocks until the drain operation completes.">natsSubscription_WaitForDrainCompletion</a></dd></dl>
<dlclass="params"><dt>Parameters</dt><dd>
<tableclass="params">
<tr><tdclass="paramname">sub</td><td>the pointer to the <aclass="el"href="group__types_group.html#ga87158ec63b4f90f69e20451624ea01d8"title="Interest on a given subject.">natsSubscription</a> object. </td></tr>
<p>In order to make sure that an asynchronous subscription's message handler is no longer invoked once the subscription is closed (<aclass="el"href="group__sub_group.html#gaee87f8be0e6c2a4693ba2cea070583ba"title="Unsubscribes.">natsSubscription_Unsubscribe</a>), the subscription should be closed from the message handler itslef.</p>
<p>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.</p>
<p>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.</p>
<dlclass="section note"><dt>Note</dt><dd>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.</dd>
<dd>
If you plan on calling this function, you should do so before calling <aclass="el"href="group__sub_group.html#ga09f285de2746a6e27fc66efd60bd3116"title="Auto-Unsubscribes.">natsSubscription_AutoUnsubscribe</a>, since there is a risk that the subscription be removed as soon as <aclass="el"href="group__sub_group.html#ga09f285de2746a6e27fc66efd60bd3116"title="Auto-Unsubscribes.">natsSubscription_AutoUnsubscribe</a> returns.</dd></dl>
<p>Calling this function on a synchronous or closed subscription will return <aclass="el"href="status_8h.html#a36c934157b663b7b5fb5d6609c897c80a273e92a0ff3b7eaf946b4b7fa6cc6c6c">NATS_INVALID_SUBSCRIPTION</a>.</p>
<dlclass="section see"><dt>See also</dt><dd><aclass="el"href="group__callbacks_group.html#ga245131e64f1d0dff7edc8ed874a07e9a"title="Callback used to notify that an object lifecycle is complete.">natsOnCompleteCB</a></dd></dl>
<dlclass="params"><dt>Parameters</dt><dd>
<tableclass="params">
<tr><tdclass="paramname">sub</td><td>the pointer to the <aclass="el"href="group__types_group.html#ga87158ec63b4f90f69e20451624ea01d8"title="Interest on a given subject.">natsSubscription</a> object </td></tr>
<tr><tdclass="paramname">cb</td><td>the callback to invoke when the last message of a closed subscription has been dispatched </td></tr>
<tr><tdclass="paramname">closure</td><td>the pointer to a user defined object (possibly <code>NULL</code>) that will be passed to the callback </td></tr>
<p>Destroys the subscription object, freeing up memory. If not already done, this call will removes interest on the subject.</p>
<dlclass="params"><dt>Parameters</dt><dd>
<tableclass="params">
<tr><tdclass="paramname">sub</td><td>the pointer to the <aclass="el"href="group__types_group.html#ga87158ec63b4f90f69e20451624ea01d8"title="Interest on a given subject.">natsSubscription</a> object to destroy. </td></tr>
</table>
</dd>
</dl>
</div>
</div>
</div><!-- contents -->
</div><!-- doc-content -->
<!-- HTML footer for doxygen 1.8.10-->
<!-- start footer part -->
<divid="nav-path"class="navpath"><!-- id is needed for treeview function! -->
<ul>
<liclass="footer">NATS.IO Supported By Synadia Communications Inc.
