Library

Functions
NATS_EXTERN natsStatus	nats_Open (int64_t lockSpinCount)
	Initializes the library.
NATS_EXTERN const char *	nats_GetVersion (void)
	Returns the Library's version.
NATS_EXTERN uint32_t	nats_GetVersionNumber (void)
	Returns the Library's version as a number.
NATS_EXTERN bool	nats_CheckCompatibility (void)
	Check that the header is compatible with the library.
NATS_EXTERN int64_t	nats_Now (void)
	Gives the current time in milliseconds.
NATS_EXTERN int64_t	nats_NowInNanoSeconds (void)
	Gives the current time in nanoseconds.
NATS_EXTERN void	nats_Sleep (int64_t sleepTime)
	Sleeps for a given number of milliseconds.
NATS_EXTERN const char *	nats_GetLastError (natsStatus *status)
	Returns the calling thread's last known error.
NATS_EXTERN natsStatus	nats_GetLastErrorStack (char *buffer, size_t bufLen)
	Returns the calling thread's last known error stack.
NATS_EXTERN void	nats_PrintLastErrorStack (FILE *file)
	Prints the calling thread's last known error stack into the file.
NATS_EXTERN natsStatus	nats_SetMessageDeliveryPoolSize (int max)
	Sets the maximum size of the global message delivery thread pool.
NATS_EXTERN void	nats_ReleaseThreadMemory (void)
	Release thread-local memory possibly allocated by the library.
NATS_EXTERN natsStatus	nats_Sign (const char *encodedSeed, const char *input, unsigned char **signature, int *signatureLength)
	Signs a given text using the provided private key.
NATS_EXTERN void	nats_Close (void)
	Tear down the library.
NATS_EXTERN natsStatus	nats_CloseAndWait (int64_t timeout)
	Tear down the library and wait for all resources to be released.

Detailed Description

Library and helper functions.

Function Documentation

nats_Open()

NATS_EXTERN natsStatus nats_Open

(

int64_t

lockSpinCount

)

This initializes the library.

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.

Warning

You must not call nats_Open and nats_Close concurrently.

Parameters

lockSpinCount

The number of times the library will spin trying to lock a mutex object.

nats_GetVersion()

NATS_EXTERN const char * nats_GetVersion

(

void

)

Returns the version of the library your application is linked with.

nats_GetVersionNumber()

NATS_EXTERN uint32_t nats_GetVersionNumber

(

void

)

The version is returned as an hexadecimal number. For instance, if the string version is "1.2.3", the value returned will be:

‍0x010203

nats_CheckCompatibility()

NATS_EXTERN bool nats_CheckCompatibility

(

void

)

The version of the header you used to compile your application may be incompatible with the library the application is linked with.

This function will check that the two are compatibles. If they are not, a message is printed and the application will exit.

Returns

true if the header and library are compatibles, otherwise the application exits.

See also

nats_GetVersion

nats_GetVersionNumber

nats_Now()

NATS_EXTERN int64_t nats_Now

(

void

)

Gives the current time in milliseconds.

nats_NowInNanoSeconds()

NATS_EXTERN int64_t nats_NowInNanoSeconds

(

void

)

Gives the current time in nanoseconds. When such granularity is not available, the time returned is still expressed in nanoseconds.

nats_Sleep()

NATS_EXTERN void nats_Sleep

(

int64_t

sleepTime

)

Causes the current thread to be suspended for at least the number of milliseconds.

Parameters

sleepTime

the number of milliseconds.

nats_GetLastError()

NATS_EXTERN const char * nats_GetLastError

(

natsStatus *

status

)

Returns the calling thread's last known error. This can be useful when natsConnection_Connect fails. Since no connection object is returned, you would not be able to call natsConnection_GetLastError.

Parameters

status

if not NULL, this function will store the last error status in there.

Returns

the thread local error string.

Warning

Do not free the string returned by this function.

nats_GetLastErrorStack()

NATS_EXTERN natsStatus nats_GetLastErrorStack	(	char *	buffer,
		size_t	bufLen )

Copies the calling thread's last known error stack into the provided buffer. If the buffer is not big enough, NATS_INSUFFICIENT_BUFFER is returned.

Parameters

buffer	the buffer into the stack is copied.
bufLen	the size of the buffer

nats_PrintLastErrorStack()

NATS_EXTERN void nats_PrintLastErrorStack

(

FILE *

file

)

This call prints the calling thread's last known error stack into the file file. It first prints the error status and the error string, then the stack.

Here is an example for a call:

Error: 29 - SSL Error - (conn.c:565): SSL handshake error: sslv3 alert bad certificate
Stack: (library version: 1.2.3-beta)
  01 - _makeTLSConn
  02 - _checkForSecure
  03 - _processExpectedInfo
  04 - _processConnInit
  05 - _connect
  06 - natsConnection_Connect

Parameters

file	the file the stack is printed to.

nats_SetMessageDeliveryPoolSize()

NATS_EXTERN natsStatus nats_SetMessageDeliveryPoolSize

(

int

max

)

Normally, each asynchronous subscriber that is created has its own message delivery thread. The advantage is that it reduces lock contentions, therefore improving performance.
However, if an application creates many subscribers, this is not scaling well since the process would use too many threads.

The library has a thread pool that can perform message delivery. If a connection is created with the proper option set (natsOptions_UseGlobalMessageDelivery), 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.

Each subscriber will be attached to a given worker on the pool so that message delivery order is guaranteed.

This call allows you to set the maximum size of the pool.

Note

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.

See also

natsOptions_UseGlobalMessageDelivery()

Environment Variables

Parameters

max	the maximum size of the pool.

nats_ReleaseThreadMemory()

NATS_EXTERN void nats_ReleaseThreadMemory

(

void

)

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.

Also, you do not need to call this in an user thread (or the main) if you are calling nats_Close() there.

nats_Sign()

NATS_EXTERN natsStatus nats_Sign	(	const char *	encodedSeed,
		const char *	input,
		unsigned char **	signature,
		int *	signatureLength )

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.

The input is a string, generally the nonce sent by the server when accepting a connection.

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 natsOptions_SetNKey(), 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.

See also

natsOptions_SetNKey()

Parameters

encodedSeed	the string encoded private key, also known as seed.
input	the input to be signed.
signature	the memory location of allocated memory containing the signed input.
signatureLength	the size of the allocated signature.

nats_Close()

NATS_EXTERN void nats_Close

(

void

)

Releases memory used by the library.

For this to take effect, all NATS objects that you have created must first be destroyed.

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 nats_Open() right away may fail. If you want to ensure that the library is fully unloaded, call nats_CloseAndWait() instead.

Note

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).

Warning

You must not call nats_Open and nats_Close concurrently.

See also

nats_CloseAndWait()

nats_CloseAndWait()

NATS_EXTERN natsStatus nats_CloseAndWait

(

int64_t

timeout

)

Similar to nats_Close() 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).

For instance, this code would "deadlock":

natsConnection_ConnectTo(&nc, NATS_DEFAULT_URL);
nats_CloseWait(0);
natsConnection_Destroy(nc);

But this would work as expected:

natsConnection_ConnectTo(&nc, NATS_DEFAULT_URL);
natsConnection_Destroy(nc);
nats_CloseWait(0);

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 nats_Close(), which will simply ensure that the library is ultimately releasing memory, the nats_CloseAndWait() API will ensure that all those internal threads have unrolled and that the memory used by the library is released before returning.

Note

If a timeout is specified, the call may return NATS_TIMEOUT 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 nats_Open() 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.

Warning

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 NATS_ILLEGAL_STATE error will be returned.

See also

nats_Close()

Parameters

timeout

the maximum time to wait for the library to be closed. If negative or 0, waits for as long as needed.