Guide for Persistence

Callable Store

It is possible for an application to start an instance of the Store to run as an independent set of threads within the application process. However, there are several restrictions:

1. The application may not make use of messaging. I.e. an application which intends to start a Store instance must not create contexts, sources, or receivers, or make any use of UM except starting (and optionally stopping) the Store. For applications that need to use messaging, it is suggested that the application create a child process from which to invoke the Store. The parent process can then use messaging freely.

2. Only a C API is provided at this time. Two API functions are available: umestored_main() to start the Store threads running, and umestored_main_shutdown() to request the Store threads to stop gracefully.

3. The umestored_main() API will not return until the Store exits, either by processing a signal, or by the application calling umestored_main_shutdown(). When umestored_main() does return, the Store is in a safe state for the application to exit.

4. Only a single instance of the Store may be started. This means that an application may not have two Stores running concurrently, and it also means that an application may not start a Store, shut it down, and then start it again. The Store API is "single use".

5. The application may not set signal handlers for SIGPIPE, SIGUSR1, SIGINT, or SIGTERM. The Store uses those signals. For applications that need to handle those signals, it is suggested that the application create a child process, as mentioned above (#1).

See umestored_main.h File Reference for API details.

The API code is not contained within the normal "lbm" library. On Linux, it is in "libumestorelib.a", a static library. On Windows, it is in "umestore.dll", a dynamic library.

For an example of how to use the umestored_main() API, see the example program Example umestored_example.c. Note that while the callable Store APIs are usable on all supported platforms, this example program is restricted to Linux due to its use of `prctl()`, a Linux-only function.