Loading...
Searching...
No Matches
Library
Functions

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