factotum/nats.zig
1
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
nats.zig/deps/nats.c/doc/html/group__library_group.html
torque 79a45fd2e3
git subrepo clone (merge) --branch=v3.6.1 https://github.com/nats-io/nats.c.git deps/nats.c 
subrepo:
  subdir:   "deps/nats.c"
  merged:   "66cec7f"
upstream:
  origin:   "https://github.com/nats-io/nats.c.git"
  branch:   "v3.6.1"
  commit:   "66cec7f"
git-subrepo:
  version:  "0.4.6"
  commit:   "b8b46501e"
2023-08-15 00:21:33 -07:00

581 lines
39 KiB
HTML
Raw Blame History

<!-- HTML header for doxygen 1.8.10-->
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.9.6"/>
<title>NATS C Client with JetStream and Streaming support: Library</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtreedata.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<link href="customdoxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td id="projectalign" style="padding-left: 0.5em;" >
<div id="projectname">NATS C Client with JetStream and Streaming support
&#160;<span id="projectnumber">3.6.1</span>
</div>
<div id="projectbrief">The nats.io C Client, Supported by Synadia Communications Inc.</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.9.6 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
var searchBox = new SearchBox("searchBox", "search/",'.html');
/* @license-end */
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
$(function() {
initMenu('',true,false,'search.php','Search');
$(document).ready(function() { init_search(); });
});
/* @license-end */
</script>
<div id="main-nav"></div>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
<div id="nav-tree">
<div id="nav-tree-contents">
<div id="nav-sync" class="sync"></div>
</div>
</div>
<div id="splitbar" style="-moz-user-select:none;"
class="ui-resizable-handle">
</div>
</div>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
$(document).ready(function(){initNavTree('group__library_group.html',''); initResizable(); });
/* @license-end */
</script>
<div id="doc-content">
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>
<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<div id="MSearchResults">
<div class="SRPage">
<div id="SRIndex">
<div id="SRResults"></div>
<div class="SRStatus" id="Loading">Loading...</div>
<div class="SRStatus" id="Searching">Searching...</div>
<div class="SRStatus" id="NoMatches">No Matches</div>
</div>
</div>
</div>
</div>
<div class="header">
<div class="summary">
<a href="#func-members">Functions</a> </div>
<div class="headertitle"><div class="title">Library<div class="ingroups"><a class="el" href="group__func_group.html">Functions</a></div></div></div>
</div><!--header-->
<div class="contents">
<table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a id="func-members" name="func-members"></a>
Functions</h2></td></tr>
<tr class="memitem:ga4a26d4caecb23348f6eee862c95fee7d"><td class="memItemLeft" align="right" valign="top"><a class="el" href="nats_8h.html#a3bc1b3fe7f64083e60c7c3b93f205bad">NATS_EXTERN</a> <a class="el" href="status_8h.html#a36c934157b663b7b5fb5d6609c897c80">natsStatus</a>&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__library_group.html#ga4a26d4caecb23348f6eee862c95fee7d">nats_Open</a> (int64_t lockSpinCount)</td></tr>
<tr class="memdesc:ga4a26d4caecb23348f6eee862c95fee7d"><td class="mdescLeft">&#160;</td><td class="mdescRight">Initializes the library. <br /></td></tr>
<tr class="separator:ga4a26d4caecb23348f6eee862c95fee7d"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:ga0d8c3df1c0c4a3d340d8ff81355fb1e8"><td class="memItemLeft" align="right" valign="top"><a class="el" href="nats_8h.html#a3bc1b3fe7f64083e60c7c3b93f205bad">NATS_EXTERN</a> const char *&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__library_group.html#ga0d8c3df1c0c4a3d340d8ff81355fb1e8">nats_GetVersion</a> (void)</td></tr>
<tr class="memdesc:ga0d8c3df1c0c4a3d340d8ff81355fb1e8"><td class="mdescLeft">&#160;</td><td class="mdescRight">Returns the Library's version. <br /></td></tr>
<tr class="separator:ga0d8c3df1c0c4a3d340d8ff81355fb1e8"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:ga5fbbaa19b0290b654d2669a05bd512e8"><td class="memItemLeft" align="right" valign="top"><a class="el" href="nats_8h.html#a3bc1b3fe7f64083e60c7c3b93f205bad">NATS_EXTERN</a> uint32_t&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__library_group.html#ga5fbbaa19b0290b654d2669a05bd512e8">nats_GetVersionNumber</a> (void)</td></tr>
<tr class="memdesc:ga5fbbaa19b0290b654d2669a05bd512e8"><td class="mdescLeft">&#160;</td><td class="mdescRight">Returns the Library's version as a number. <br /></td></tr>
<tr class="separator:ga5fbbaa19b0290b654d2669a05bd512e8"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:ga8c2ad4df801bd9d11564587ed3a7081e"><td class="memItemLeft" align="right" valign="top"><a class="el" href="nats_8h.html#a3bc1b3fe7f64083e60c7c3b93f205bad">NATS_EXTERN</a> bool&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__library_group.html#ga8c2ad4df801bd9d11564587ed3a7081e">nats_CheckCompatibility</a> (void)</td></tr>
<tr class="memdesc:ga8c2ad4df801bd9d11564587ed3a7081e"><td class="mdescLeft">&#160;</td><td class="mdescRight">Check that the header is compatible with the library. <br /></td></tr>
<tr class="separator:ga8c2ad4df801bd9d11564587ed3a7081e"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:gaa3c10ba3ae001595007ad0dc5dccc15e"><td class="memItemLeft" align="right" valign="top"><a class="el" href="nats_8h.html#a3bc1b3fe7f64083e60c7c3b93f205bad">NATS_EXTERN</a> int64_t&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__library_group.html#gaa3c10ba3ae001595007ad0dc5dccc15e">nats_Now</a> (void)</td></tr>
<tr class="memdesc:gaa3c10ba3ae001595007ad0dc5dccc15e"><td class="mdescLeft">&#160;</td><td class="mdescRight">Gives the current time in milliseconds. <br /></td></tr>
<tr class="separator:gaa3c10ba3ae001595007ad0dc5dccc15e"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:gacf5e423920d6a647df3bbf7de39d5223"><td class="memItemLeft" align="right" valign="top"><a class="el" href="nats_8h.html#a3bc1b3fe7f64083e60c7c3b93f205bad">NATS_EXTERN</a> int64_t&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__library_group.html#gacf5e423920d6a647df3bbf7de39d5223">nats_NowInNanoSeconds</a> (void)</td></tr>
<tr class="memdesc:gacf5e423920d6a647df3bbf7de39d5223"><td class="mdescLeft">&#160;</td><td class="mdescRight">Gives the current time in nanoseconds. <br /></td></tr>
<tr class="separator:gacf5e423920d6a647df3bbf7de39d5223"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:gad5040264cd4b1404956babf3c03a4f09"><td class="memItemLeft" align="right" valign="top"><a class="el" href="nats_8h.html#a3bc1b3fe7f64083e60c7c3b93f205bad">NATS_EXTERN</a> void&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__library_group.html#gad5040264cd4b1404956babf3c03a4f09">nats_Sleep</a> (int64_t sleepTime)</td></tr>
<tr class="memdesc:gad5040264cd4b1404956babf3c03a4f09"><td class="mdescLeft">&#160;</td><td class="mdescRight">Sleeps for a given number of milliseconds. <br /></td></tr>
<tr class="separator:gad5040264cd4b1404956babf3c03a4f09"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:gadecfd49a58b581dbba40da77b195fd85"><td class="memItemLeft" align="right" valign="top"><a class="el" href="nats_8h.html#a3bc1b3fe7f64083e60c7c3b93f205bad">NATS_EXTERN</a> const char *&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__library_group.html#gadecfd49a58b581dbba40da77b195fd85">nats_GetLastError</a> (<a class="el" href="status_8h.html#a36c934157b663b7b5fb5d6609c897c80">natsStatus</a> *status)</td></tr>
<tr class="memdesc:gadecfd49a58b581dbba40da77b195fd85"><td class="mdescLeft">&#160;</td><td class="mdescRight">Returns the calling thread's last known error. <br /></td></tr>
<tr class="separator:gadecfd49a58b581dbba40da77b195fd85"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:gaca24172e1b97ca01cee29ca437f5702e"><td class="memItemLeft" align="right" valign="top"><a class="el" href="nats_8h.html#a3bc1b3fe7f64083e60c7c3b93f205bad">NATS_EXTERN</a> <a class="el" href="status_8h.html#a36c934157b663b7b5fb5d6609c897c80">natsStatus</a>&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__library_group.html#gaca24172e1b97ca01cee29ca437f5702e">nats_GetLastErrorStack</a> (char *buffer, size_t bufLen)</td></tr>
<tr class="memdesc:gaca24172e1b97ca01cee29ca437f5702e"><td class="mdescLeft">&#160;</td><td class="mdescRight">Returns the calling thread's last known error stack. <br /></td></tr>
<tr class="separator:gaca24172e1b97ca01cee29ca437f5702e"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:ga5fab3b18c4fe3630254483575f6066f4"><td class="memItemLeft" align="right" valign="top"><a class="el" href="nats_8h.html#a3bc1b3fe7f64083e60c7c3b93f205bad">NATS_EXTERN</a> void&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__library_group.html#ga5fab3b18c4fe3630254483575f6066f4">nats_PrintLastErrorStack</a> (FILE *file)</td></tr>
<tr class="memdesc:ga5fab3b18c4fe3630254483575f6066f4"><td class="mdescLeft">&#160;</td><td class="mdescRight">Prints the calling thread's last known error stack into the file. <br /></td></tr>
<tr class="separator:ga5fab3b18c4fe3630254483575f6066f4"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:gab21e94ce7a7d226611ea2c05914cf19d"><td class="memItemLeft" align="right" valign="top"><a class="el" href="nats_8h.html#a3bc1b3fe7f64083e60c7c3b93f205bad">NATS_EXTERN</a> <a class="el" href="status_8h.html#a36c934157b663b7b5fb5d6609c897c80">natsStatus</a>&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__library_group.html#gab21e94ce7a7d226611ea2c05914cf19d">nats_SetMessageDeliveryPoolSize</a> (int max)</td></tr>
<tr class="memdesc:gab21e94ce7a7d226611ea2c05914cf19d"><td class="mdescLeft">&#160;</td><td class="mdescRight">Sets the maximum size of the global message delivery thread pool. <br /></td></tr>
<tr class="separator:gab21e94ce7a7d226611ea2c05914cf19d"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:gafe171baefa00a85b77205116e9f3e48a"><td class="memItemLeft" align="right" valign="top"><a class="el" href="nats_8h.html#a3bc1b3fe7f64083e60c7c3b93f205bad">NATS_EXTERN</a> void&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__library_group.html#gafe171baefa00a85b77205116e9f3e48a">nats_ReleaseThreadMemory</a> (void)</td></tr>
<tr class="memdesc:gafe171baefa00a85b77205116e9f3e48a"><td class="mdescLeft">&#160;</td><td class="mdescRight">Release thread-local memory possibly allocated by the library. <br /></td></tr>
<tr class="separator:gafe171baefa00a85b77205116e9f3e48a"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:gaf781f246e2e0ab24623ca667c48dc3ba"><td class="memItemLeft" align="right" valign="top"><a class="el" href="nats_8h.html#a3bc1b3fe7f64083e60c7c3b93f205bad">NATS_EXTERN</a> <a class="el" href="status_8h.html#a36c934157b663b7b5fb5d6609c897c80">natsStatus</a>&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__library_group.html#gaf781f246e2e0ab24623ca667c48dc3ba">nats_Sign</a> (const char *encodedSeed, const char *input, unsigned char **signature, int *signatureLength)</td></tr>
<tr class="memdesc:gaf781f246e2e0ab24623ca667c48dc3ba"><td class="mdescLeft">&#160;</td><td class="mdescRight">Signs a given text using the provided private key. <br /></td></tr>
<tr class="separator:gaf781f246e2e0ab24623ca667c48dc3ba"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:gae75131e0ce4e5b89d0f82ea7892f112e"><td class="memItemLeft" align="right" valign="top"><a class="el" href="nats_8h.html#a3bc1b3fe7f64083e60c7c3b93f205bad">NATS_EXTERN</a> void&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__library_group.html#gae75131e0ce4e5b89d0f82ea7892f112e">nats_Close</a> (void)</td></tr>
<tr class="memdesc:gae75131e0ce4e5b89d0f82ea7892f112e"><td class="mdescLeft">&#160;</td><td class="mdescRight">Tear down the library. <br /></td></tr>
<tr class="separator:gae75131e0ce4e5b89d0f82ea7892f112e"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:gaf75bb5b38bf32e6a8f43e54068625903"><td class="memItemLeft" align="right" valign="top"><a class="el" href="nats_8h.html#a3bc1b3fe7f64083e60c7c3b93f205bad">NATS_EXTERN</a> <a class="el" href="status_8h.html#a36c934157b663b7b5fb5d6609c897c80">natsStatus</a>&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__library_group.html#gaf75bb5b38bf32e6a8f43e54068625903">nats_CloseAndWait</a> (int64_t timeout)</td></tr>
<tr class="memdesc:gaf75bb5b38bf32e6a8f43e54068625903"><td class="mdescLeft">&#160;</td><td class="mdescRight">Tear down the library and wait for all resources to be released. <br /></td></tr>
<tr class="separator:gaf75bb5b38bf32e6a8f43e54068625903"><td class="memSeparator" colspan="2">&#160;</td></tr>
</table>
<a name="details" id="details"></a><h2 class="groupheader">Detailed Description</h2>
<p>Library and helper functions. </p>
<h2 class="groupheader">Function Documentation</h2>
<a id="ga4a26d4caecb23348f6eee862c95fee7d" name="ga4a26d4caecb23348f6eee862c95fee7d"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ga4a26d4caecb23348f6eee862c95fee7d">&#9670;&#160;</a></span>nats_Open()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname"><a class="el" href="nats_8h.html#a3bc1b3fe7f64083e60c7c3b93f205bad">NATS_EXTERN</a> <a class="el" href="status_8h.html#a36c934157b663b7b5fb5d6609c897c80">natsStatus</a> nats_Open </td>
<td>(</td>
<td class="paramtype">int64_t&#160;</td>
<td class="paramname"><em>lockSpinCount</em></td><td>)</td>
<td></td>
</tr>
</table>
</div><div class="memdoc">
<p>This initializes the library.</p>
<p>It is invoked automatically when creating a connection, using a default spin count. However, you can call this explicitly before creating the very first connection in order for your chosen spin count to take effect.</p>
<dl class="section warning"><dt>Warning</dt><dd>You must not call <a class="el" href="group__library_group.html#ga4a26d4caecb23348f6eee862c95fee7d" title="Initializes the library.">nats_Open</a> and <a class="el" href="group__library_group.html#gae75131e0ce4e5b89d0f82ea7892f112e" title="Tear down the library.">nats_Close</a> concurrently.</dd></dl>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">lockSpinCount</td><td>The number of times the library will spin trying to lock a mutex object. </td></tr>
</table>
</dd>
</dl>
</div>
</div>
<a id="ga0d8c3df1c0c4a3d340d8ff81355fb1e8" name="ga0d8c3df1c0c4a3d340d8ff81355fb1e8"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ga0d8c3df1c0c4a3d340d8ff81355fb1e8">&#9670;&#160;</a></span>nats_GetVersion()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname"><a class="el" href="nats_8h.html#a3bc1b3fe7f64083e60c7c3b93f205bad">NATS_EXTERN</a> const char * nats_GetVersion </td>
<td>(</td>
<td class="paramtype">void&#160;</td>
<td class="paramname"></td><td>)</td>
<td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Returns the version of the library your application is linked with. </p>
</div>
</div>
<a id="ga5fbbaa19b0290b654d2669a05bd512e8" name="ga5fbbaa19b0290b654d2669a05bd512e8"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ga5fbbaa19b0290b654d2669a05bd512e8">&#9670;&#160;</a></span>nats_GetVersionNumber()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname"><a class="el" href="nats_8h.html#a3bc1b3fe7f64083e60c7c3b93f205bad">NATS_EXTERN</a> uint32_t nats_GetVersionNumber </td>
<td>(</td>
<td class="paramtype">void&#160;</td>
<td class="paramname"></td><td>)</td>
<td></td>
</tr>
</table>
</div><div class="memdoc">
<p>The version is returned as an hexadecimal number. For instance, if the string version is "1.2.3", the value returned will be:</p>
<blockquote class="doxtable">
<p>&zwj;0x010203 </p>
</blockquote>
</div>
</div>
<a id="ga8c2ad4df801bd9d11564587ed3a7081e" name="ga8c2ad4df801bd9d11564587ed3a7081e"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ga8c2ad4df801bd9d11564587ed3a7081e">&#9670;&#160;</a></span>nats_CheckCompatibility()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname"><a class="el" href="nats_8h.html#a3bc1b3fe7f64083e60c7c3b93f205bad">NATS_EXTERN</a> bool nats_CheckCompatibility </td>
<td>(</td>
<td class="paramtype">void&#160;</td>
<td class="paramname"></td><td>)</td>
<td></td>
</tr>
</table>
</div><div class="memdoc">
<p>The version of the header you used to compile your application may be incompatible with the library the application is linked with.</p>
<p>This function will check that the two are compatibles. If they are not, a message is printed and the application will exit.</p>
<dl class="section return"><dt>Returns</dt><dd><code>true</code> if the header and library are compatibles, otherwise the application exits.</dd></dl>
<dl class="section see"><dt>See also</dt><dd><a class="el" href="group__library_group.html#ga0d8c3df1c0c4a3d340d8ff81355fb1e8" title="Returns the Library&#39;s version.">nats_GetVersion</a> </dd>
<dd>
<a class="el" href="group__library_group.html#ga5fbbaa19b0290b654d2669a05bd512e8" title="Returns the Library&#39;s version as a number.">nats_GetVersionNumber</a> </dd></dl>
</div>
</div>
<a id="gaa3c10ba3ae001595007ad0dc5dccc15e" name="gaa3c10ba3ae001595007ad0dc5dccc15e"></a>
<h2 class="memtitle"><span class="permalink"><a href="#gaa3c10ba3ae001595007ad0dc5dccc15e">&#9670;&#160;</a></span>nats_Now()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname"><a class="el" href="nats_8h.html#a3bc1b3fe7f64083e60c7c3b93f205bad">NATS_EXTERN</a> int64_t nats_Now </td>
<td>(</td>
<td class="paramtype">void&#160;</td>
<td class="paramname"></td><td>)</td>
<td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Gives the current time in milliseconds. </p>
</div>
</div>
<a id="gacf5e423920d6a647df3bbf7de39d5223" name="gacf5e423920d6a647df3bbf7de39d5223"></a>
<h2 class="memtitle"><span class="permalink"><a href="#gacf5e423920d6a647df3bbf7de39d5223">&#9670;&#160;</a></span>nats_NowInNanoSeconds()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname"><a class="el" href="nats_8h.html#a3bc1b3fe7f64083e60c7c3b93f205bad">NATS_EXTERN</a> int64_t nats_NowInNanoSeconds </td>
<td>(</td>
<td class="paramtype">void&#160;</td>
<td class="paramname"></td><td>)</td>
<td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Gives the current time in nanoseconds. When such granularity is not available, the time returned is still expressed in nanoseconds. </p>
</div>
</div>
<a id="gad5040264cd4b1404956babf3c03a4f09" name="gad5040264cd4b1404956babf3c03a4f09"></a>
<h2 class="memtitle"><span class="permalink"><a href="#gad5040264cd4b1404956babf3c03a4f09">&#9670;&#160;</a></span>nats_Sleep()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname"><a class="el" href="nats_8h.html#a3bc1b3fe7f64083e60c7c3b93f205bad">NATS_EXTERN</a> void nats_Sleep </td>
<td>(</td>
<td class="paramtype">int64_t&#160;</td>
<td class="paramname"><em>sleepTime</em></td><td>)</td>
<td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Causes the current thread to be suspended for at least the number of milliseconds.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">sleepTime</td><td>the number of milliseconds. </td></tr>
</table>
</dd>
</dl>
</div>
</div>
<a id="gadecfd49a58b581dbba40da77b195fd85" name="gadecfd49a58b581dbba40da77b195fd85"></a>
<h2 class="memtitle"><span class="permalink"><a href="#gadecfd49a58b581dbba40da77b195fd85">&#9670;&#160;</a></span>nats_GetLastError()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname"><a class="el" href="nats_8h.html#a3bc1b3fe7f64083e60c7c3b93f205bad">NATS_EXTERN</a> const char * nats_GetLastError </td>
<td>(</td>
<td class="paramtype"><a class="el" href="status_8h.html#a36c934157b663b7b5fb5d6609c897c80">natsStatus</a> *&#160;</td>
<td class="paramname"><em>status</em></td><td>)</td>
<td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Returns the calling thread's last known error. This can be useful when <a class="el" href="group__conn_mgt_group.html#ga740be1ba16a8570eb98ef6755ebf52ce" title="Connects to a NATS Server using the provided options.">natsConnection_Connect</a> fails. Since no connection object is returned, you would not be able to call <a class="el" href="group__conn_mgt_group.html#gab6cfa9cb6857ae10f096a94f5e244e63" title="Gets the last connection error.">natsConnection_GetLastError</a>.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">status</td><td>if not <code>NULL</code>, this function will store the last error status in there. </td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>the thread local error string.</dd></dl>
<dl class="section warning"><dt>Warning</dt><dd>Do not free the string returned by this function. </dd></dl>
</div>
</div>
<a id="gaca24172e1b97ca01cee29ca437f5702e" name="gaca24172e1b97ca01cee29ca437f5702e"></a>
<h2 class="memtitle"><span class="permalink"><a href="#gaca24172e1b97ca01cee29ca437f5702e">&#9670;&#160;</a></span>nats_GetLastErrorStack()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname"><a class="el" href="nats_8h.html#a3bc1b3fe7f64083e60c7c3b93f205bad">NATS_EXTERN</a> <a class="el" href="status_8h.html#a36c934157b663b7b5fb5d6609c897c80">natsStatus</a> nats_GetLastErrorStack </td>
<td>(</td>
<td class="paramtype">char *&#160;</td>
<td class="paramname"><em>buffer</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">size_t&#160;</td>
<td class="paramname"><em>bufLen</em>&#160;</td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Copies the calling thread's last known error stack into the provided buffer. If the buffer is not big enough, <a class="el" href="status_8h.html#a36c934157b663b7b5fb5d6609c897c80a317fb9be1a80f6b1877f96a9a2db16ad" title="A buffer is not large enough to accommodate the data.">NATS_INSUFFICIENT_BUFFER</a> is returned.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">buffer</td><td>the buffer into the stack is copied. </td></tr>
<tr><td class="paramname">bufLen</td><td>the size of the buffer </td></tr>
</table>
</dd>
</dl>
</div>
</div>
<a id="ga5fab3b18c4fe3630254483575f6066f4" name="ga5fab3b18c4fe3630254483575f6066f4"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ga5fab3b18c4fe3630254483575f6066f4">&#9670;&#160;</a></span>nats_PrintLastErrorStack()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname"><a class="el" href="nats_8h.html#a3bc1b3fe7f64083e60c7c3b93f205bad">NATS_EXTERN</a> void nats_PrintLastErrorStack </td>
<td>(</td>
<td class="paramtype">FILE *&#160;</td>
<td class="paramname"><em>file</em></td><td>)</td>
<td></td>
</tr>
</table>
</div><div class="memdoc">
<p>This call prints the calling thread's last known error stack into the file <code>file</code>. It first prints the error status and the error string, then the stack.</p>
<p>Here is an example for a call:</p>
<div class="fragment"><div class="line">Error: 29 - SSL Error - (conn.c:565): SSL handshake error: sslv3 alert bad certificate</div>
<div class="line">Stack: (library version: 1.2.3-beta)</div>
<div class="line"> 01 - _makeTLSConn</div>
<div class="line"> 02 - _checkForSecure</div>
<div class="line"> 03 - _processExpectedInfo</div>
<div class="line"> 04 - _processConnInit</div>
<div class="line"> 05 - _connect</div>
<div class="line"> 06 - natsConnection_Connect</div>
</div><!-- fragment --><dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">file</td><td>the file the stack is printed to. </td></tr>
</table>
</dd>
</dl>
</div>
</div>
<a id="gab21e94ce7a7d226611ea2c05914cf19d" name="gab21e94ce7a7d226611ea2c05914cf19d"></a>
<h2 class="memtitle"><span class="permalink"><a href="#gab21e94ce7a7d226611ea2c05914cf19d">&#9670;&#160;</a></span>nats_SetMessageDeliveryPoolSize()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname"><a class="el" href="nats_8h.html#a3bc1b3fe7f64083e60c7c3b93f205bad">NATS_EXTERN</a> <a class="el" href="status_8h.html#a36c934157b663b7b5fb5d6609c897c80">natsStatus</a> nats_SetMessageDeliveryPoolSize </td>
<td>(</td>
<td class="paramtype">int&#160;</td>
<td class="paramname"><em>max</em></td><td>)</td>
<td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Normally, each asynchronous subscriber that is created has its own message delivery thread. The advantage is that it reduces lock contentions, therefore improving performance.<br />
However, if an application creates many subscribers, this is not scaling well since the process would use too many threads.</p>
<p>The library has a thread pool that can perform message delivery. If a connection is created with the proper option set (<a class="el" href="group__opts_group.html#gabf060c92648b50c069f0abe7cbb06f1c" title="Switch on/off the use of a central message delivery thread pool.">natsOptions_UseGlobalMessageDelivery</a>), then this thread pool will be responsible for delivering the messages. The thread pool is lazily initialized, that is, no thread is used as long as no subscriber (requiring global message delivery) is created.</p>
<p>Each subscriber will be attached to a given worker on the pool so that message delivery order is guaranteed.</p>
<p>This call allows you to set the maximum size of the pool.</p>
<dl class="section note"><dt>Note</dt><dd>At this time, a pool does not shrink, but the caller will not get an error when calling this function with a size smaller than the current size.</dd></dl>
<dl class="section see"><dt>See also</dt><dd><a class="el" href="group__opts_group.html#gabf060c92648b50c069f0abe7cbb06f1c" title="Switch on/off the use of a central message delivery thread pool.">natsOptions_UseGlobalMessageDelivery()</a> </dd>
<dd>
<a class="el" href="group__env_variables_group.html">Environment Variables</a></dd></dl>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">max</td><td>the maximum size of the pool. </td></tr>
</table>
</dd>
</dl>
</div>
</div>
<a id="gafe171baefa00a85b77205116e9f3e48a" name="gafe171baefa00a85b77205116e9f3e48a"></a>
<h2 class="memtitle"><span class="permalink"><a href="#gafe171baefa00a85b77205116e9f3e48a">&#9670;&#160;</a></span>nats_ReleaseThreadMemory()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname"><a class="el" href="nats_8h.html#a3bc1b3fe7f64083e60c7c3b93f205bad">NATS_EXTERN</a> void nats_ReleaseThreadMemory </td>
<td>(</td>
<td class="paramtype">void&#160;</td>
<td class="paramname"></td><td>)</td>
<td></td>
</tr>
</table>
</div><div class="memdoc">
<p>This needs to be called on user-created threads where NATS calls are performed. This does not need to be called in threads created by the library. For instance, do not call this function in the message handler that you specify when creating a subscription.</p>
<p>Also, you do not need to call this in an user thread (or the main) if you are calling <a class="el" href="group__library_group.html#gae75131e0ce4e5b89d0f82ea7892f112e" title="Tear down the library.">nats_Close()</a> there. </p>
</div>
</div>
<a id="gaf781f246e2e0ab24623ca667c48dc3ba" name="gaf781f246e2e0ab24623ca667c48dc3ba"></a>
<h2 class="memtitle"><span class="permalink"><a href="#gaf781f246e2e0ab24623ca667c48dc3ba">&#9670;&#160;</a></span>nats_Sign()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname"><a class="el" href="nats_8h.html#a3bc1b3fe7f64083e60c7c3b93f205bad">NATS_EXTERN</a> <a class="el" href="status_8h.html#a36c934157b663b7b5fb5d6609c897c80">natsStatus</a> nats_Sign </td>
<td>(</td>
<td class="paramtype">const char *&#160;</td>
<td class="paramname"><em>encodedSeed</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const char *&#160;</td>
<td class="paramname"><em>input</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">unsigned char **&#160;</td>
<td class="paramname"><em>signature</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int *&#160;</td>
<td class="paramname"><em>signatureLength</em>&#160;</td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
<p>The key is the encoded string representation of the private key, or seed. This is what you get when generating an NKey using NATS tooling.</p>
<p>The input is a string, generally the nonce sent by the server when accepting a connection.</p>
<p>This function signs the input and returns the signature through the output arguments. This call allocates memory necessary to hold the signature. If this is used as part of the signature callback passed to <a class="el" href="group__opts_group.html#ga0290eac4665569c850468d9f00e246a0" title="Sets the NKey public key and signature callback.">natsOptions_SetNKey()</a>, then the memory will be automatically freed by the library after the signature has been inserted in the CONNECT protocol. If this function is used outside of this context, it is the user responsibility to free the allocated memory when no longer needed.</p>
<dl class="section see"><dt>See also</dt><dd><a class="el" href="group__opts_group.html#ga0290eac4665569c850468d9f00e246a0" title="Sets the NKey public key and signature callback.">natsOptions_SetNKey()</a></dd></dl>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">encodedSeed</td><td>the string encoded private key, also known as seed. </td></tr>
<tr><td class="paramname">input</td><td>the input to be signed. </td></tr>
<tr><td class="paramname">signature</td><td>the memory location of allocated memory containing the signed input. </td></tr>
<tr><td class="paramname">signatureLength</td><td>the size of the allocated signature. </td></tr>
</table>
</dd>
</dl>
</div>
</div>
<a id="gae75131e0ce4e5b89d0f82ea7892f112e" name="gae75131e0ce4e5b89d0f82ea7892f112e"></a>
<h2 class="memtitle"><span class="permalink"><a href="#gae75131e0ce4e5b89d0f82ea7892f112e">&#9670;&#160;</a></span>nats_Close()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname"><a class="el" href="nats_8h.html#a3bc1b3fe7f64083e60c7c3b93f205bad">NATS_EXTERN</a> void nats_Close </td>
<td>(</td>
<td class="paramtype">void&#160;</td>
<td class="paramname"></td><td>)</td>
<td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Releases memory used by the library.</p>
<p>For this to take effect, all NATS objects that you have created must first be destroyed.</p>
<p>This call does not block and it is possible that the library is not unloaded right away if there are still internal threads referencing it, so calling <a class="el" href="group__library_group.html#ga4a26d4caecb23348f6eee862c95fee7d" title="Initializes the library.">nats_Open()</a> right away may fail. If you want to ensure that the library is fully unloaded, call <a class="el" href="group__library_group.html#gaf75bb5b38bf32e6a8f43e54068625903" title="Tear down the library and wait for all resources to be released.">nats_CloseAndWait()</a> instead.</p>
<dl class="section note"><dt>Note</dt><dd>There are still a small number of thread local keys and a mutex that are not freed until the application exit (in which case a final cleanup is executed).</dd></dl>
<dl class="section warning"><dt>Warning</dt><dd>You must not call <a class="el" href="group__library_group.html#ga4a26d4caecb23348f6eee862c95fee7d" title="Initializes the library.">nats_Open</a> and <a class="el" href="group__library_group.html#gae75131e0ce4e5b89d0f82ea7892f112e" title="Tear down the library.">nats_Close</a> concurrently.</dd></dl>
<dl class="section see"><dt>See also</dt><dd><a class="el" href="group__library_group.html#gaf75bb5b38bf32e6a8f43e54068625903" title="Tear down the library and wait for all resources to be released.">nats_CloseAndWait()</a> </dd></dl>
</div>
</div>
<a id="gaf75bb5b38bf32e6a8f43e54068625903" name="gaf75bb5b38bf32e6a8f43e54068625903"></a>
<h2 class="memtitle"><span class="permalink"><a href="#gaf75bb5b38bf32e6a8f43e54068625903">&#9670;&#160;</a></span>nats_CloseAndWait()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname"><a class="el" href="nats_8h.html#a3bc1b3fe7f64083e60c7c3b93f205bad">NATS_EXTERN</a> <a class="el" href="status_8h.html#a36c934157b663b7b5fb5d6609c897c80">natsStatus</a> nats_CloseAndWait </td>
<td>(</td>
<td class="paramtype">int64_t&#160;</td>
<td class="paramname"><em>timeout</em></td><td>)</td>
<td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Similar to <a class="el" href="group__library_group.html#gae75131e0ce4e5b89d0f82ea7892f112e" title="Tear down the library.">nats_Close()</a> except that this call will make sure that all references to the library are decremented before returning (up to the given timeout). Internal threads (such as subscriptions dispatchers, etc..) hold a reference to the library. Only when all references have been released that this call will return. It means that you must call all the "destroy" calls before calling this function, otherwise it will block forever (or up to given timeout).</p>
<p>For instance, this code would "deadlock": </p><div class="fragment"><div class="line">natsConnection_ConnectTo(&amp;nc, NATS_DEFAULT_URL);</div>
<div class="line">nats_CloseWait(0);</div>
<div class="line">natsConnection_Destroy(nc);</div>
</div><!-- fragment --><p> But this would work as expected: </p><div class="fragment"><div class="line">natsConnection_ConnectTo(&amp;nc, NATS_DEFAULT_URL);</div>
<div class="line">natsConnection_Destroy(nc);</div>
<div class="line">nats_CloseWait(0);</div>
</div><!-- fragment --><p> The library and other objects (such as connections, subscriptions, etc) use internal threads. After the destroy call, it is possible or even likely that some threads are still running, holding references to the library. Unlike <a class="el" href="group__library_group.html#gae75131e0ce4e5b89d0f82ea7892f112e" title="Tear down the library.">nats_Close()</a>, which will simply ensure that the library is ultimately releasing memory, the <a class="el" href="group__library_group.html#gaf75bb5b38bf32e6a8f43e54068625903" title="Tear down the library and wait for all resources to be released.">nats_CloseAndWait()</a> API will ensure that all those internal threads have unrolled and that the memory used by the library is released before returning.</p>
<dl class="section note"><dt>Note</dt><dd>If a timeout is specified, the call may return <a class="el" href="status_8h.html#a36c934157b663b7b5fb5d6609c897c80ab88994c9ea9889ac4d9d656d62f550ed">NATS_TIMEOUT</a> but the library is still being tear down and memory will be released. The error is just to notify you that the operation did not complete in the allotted time. Calling <a class="el" href="group__library_group.html#ga4a26d4caecb23348f6eee862c95fee7d" title="Initializes the library.">nats_Open()</a> in this case (or any implicit opening of the library) may result in an error since the library may still be in the process of being closed.</dd></dl>
<dl class="section warning"><dt>Warning</dt><dd>Due to the blocking nature it is illegal to call this from any NATS thread (such as message or connection callbacks). If trying to do so, a <a class="el" href="status_8h.html#a36c934157b663b7b5fb5d6609c897c80a9bb78b4f245d2870040d25c450febd4b">NATS_ILLEGAL_STATE</a> error will be returned.</dd></dl>
<dl class="section see"><dt>See also</dt><dd><a class="el" href="group__library_group.html#gae75131e0ce4e5b89d0f82ea7892f112e" title="Tear down the library.">nats_Close()</a></dd></dl>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">timeout</td><td>the maximum time to wait for the library to be closed. If negative or 0, waits for as long as needed. </td></tr>
</table>
</dd>
</dl>
</div>
</div>
</div><!-- contents -->
</div><!-- doc-content -->
<!-- HTML footer for doxygen 1.8.10-->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
<ul>
<li class="footer">NATS.IO Supported By Synadia Communications Inc.
<a href="http://www.nats.io">
</a></li>
</ul>
</div>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink