Startup & Shutdown#

Functions#

char const * omniClientGetVersionString(): Returns a human-readable version string.
bool omniClientInitialize(uint64_t version): Perform some one-time initialization.
void omniClientSetProductInfo(char const *name, char const *version, char const *extra): Sets product information that's sent to Nucleus when connecting.
void omniClientShutdown(): Terminate all connections and free everything.
void omniClientWriteChromeTrace(): Write Chrome trace events to file and reset the trace buffer.

Functions#

char const *omniClientGetVersionString()#

Returns a human-readable version string.

The format is not guaranteed to remain consistent from one version to another, so please don’t try to parse it. Instead, use OMNICLIENT_VERSION_MAJOR OMNICLIENT_VERSION_MINOR and OMNICLIENT_VERSION_PATCH if you are trying to conditionally perform an operation depending on which version of the library is being used.

Returns:: A human-readable version string

bool omniClientInitialize(uint64_t version)#

Perform some one-time initialization.

Note

It’s not strictly necessary to call this, because it will be automatically called the first time any of the other functions are called (except the logging functions). The reason you may want to manually call it are to verify the version in the header and dll match, and also so you have a consistent place where the library is initialized. This can sometimes be important for logging (so you get the initialization messages at the same place in the log every time).

Parameters:: version – Pass kOmniClientVersion to ensure the header matches the dll.
Returns:: false if there was a version mismatch.

void omniClientSetProductInfo( char const *name, char const *version, char const *extra, )#

Sets product information that’s sent to Nucleus when connecting.

If you’re already connected to a Nucleus server, this will not send the new values to the server, only on reconnect. For this reason you should set the product information prior to connecting.

This is also used in Hub to help identify which applications are running.

Parameters:

name – The human-readable name of this product
version – The version of this product (not the client library version)
extra – Any additional information you think would be valuable in the logs

void omniClientShutdown()#

Terminate all connections and free everything.

Only call this once, when the entire program is terminating.

Warning

It’s not safe to call any functions (not even omniClientInitialize!) after calling this.

void omniClientWriteChromeTrace()#

Write Chrome trace events to file and reset the trace buffer.

This function writes all accumulated Chrome trace events to the file specified by the OMNICLIENT_ENABLE_CHROME_TRACING environment variable, then clears the trace buffer and resets the timing. This allows you to periodically flush traces without having to wait for shutdown.

Note

Chrome tracing is only active if the OMNICLIENT_ENABLE_CHROME_TRACING environment variable is set to a file path (e.g., “/path/to/trace.json”). If the variable is not set or is empty, this function does nothing.

Note

This function is thread-safe.