UnQLite C/C++ API Reference - Global Library Management Interfaces.

Syntax

int unqlite_lib_config(int nConfigOp,...);

int unqlite_lib_init(void);

int unqlite_lib_shutdown(void);

int unqlite_lib_is_threadsafe(void);

const char * unqlite_lib_version(void);

const char * unqlite_lib_signature(void);

const char * unqlite_lib_ident(void);

const char * unqlite_lib_copyright(void);

Global Library Management Interfaces.

Description

The unqlite_lib_init() routine initializes the UnQLite library. The unqlite_lib_shutdown() routine deallocates any resources that were allocated by unqlite_lib_init() and close any subsequent database handles. These routines are designed to aid in process initialization and shutdown on embedded systems. Workstation applications using UnQLite normally do not need to invoke either of these routines.

Note that UnQLite is a self initializing library and so a manual call to unqlite_lib_init() is not needed. That is, the first call to unqlite_open() will automatically initialize the library.

A call to unqlite_lib_init() is an "effective" call if it is the first time unqlite_lib_init() is invoked during the lifetime of the process, or if it is the first time unqlite_lib_init() is invoked following a call to unqlite_lib_shutdown(). Only an effective call of unqlite_lib_init() does any initialization. All other calls are harmless no-ops.

A call to unqlite_lib_shutdown() is an "effective" call if it is the first call to unqlite_lib_shutdown() since the last unqlite_lib_init() . Only an effective call to unqlite_lib_shutdown() does any deinitialization. All other valid calls to unqlite_lib_shutdown() are harmless no-ops.

The unqlite_lib_init() interface is threadsafe, but unqlite_lib_shutdown() is not. The unqlite_lib_shutdown() interface must only be called from a single thread. This routine will take care of destroying any open database handle and their active virtual machines.

The unqlite_lib_config() interface is used to make global configuration changes to UnQLite in order to tune UnQLite to the specific needs of the application. The default configuration is recommended for most applications and so this routine is usually not necessary. It is provided to support rare applications with unusual needs.

The unqlite_lib_config() interface is not threadsafe. The application must insure that no other unqlite interfaces are invoked by other threads while unqlite_lib_config() is running. Furthermore, unqlite_lib_config() may only be invoked prior to library initialization using unqlite_lib_init() or after shutdown via unqlite_lib_shutdown().

The first argument to unqlite_lib_config() is an integer configuration option that determines what property of UnQLite is to be configured. Subsequent arguments vary depending on the configuration option in the first argument. Here is the list of allowed verbs

Configuration Verb	Expected Arguments	Description
UNQLITE_LIB_CONFIG_PAGE_SIZE	One Argument: int iPageSize	This option let you set a new database page size in bytes. The default page size (4096 Bytes) is recommended for most applications, but application can use this option to experiment with other page sizes. A valid page size must be a power of two between 512 and 65535.
UNQLITE_LIB_CONFIG_STORAGE_ENGINE	One Argument: *unqlite_kv_methods pKvEngine**	Install a foreign Key/Value storage engine. This option is reserved for future usage.
UNQLITE_LIB_CONFIG_VFS	One Argument: *const unqlite_vfs pVfs**	This option takes a single argument which is a pointer to an instance of the unqlite_vfs structure. The argument specifies alternative virtual file system methods to be used in place of the built-in VFS which is the recommended one for Windows and UNIX systems. Note that UnQLite will not make a private copy of the content of the unqlite_vfs structure which mean that the instance must be available during the life of the library.
UNQLITE_LIB_CONFIG_USER_MALLOC	One Argument: *const SyMemMethods pMethods**	This option takes a single argument which is a pointer to an instance of the SyMemMethods structure. The argument specifies alternative low-level memory allocation routines to be used in place of the memory allocation routines built into UnQLite. Note that UnQLite will not make a private copy of the content of the SyMemMethods structure which mean that the instance must be available during the life of the library.
UNQLITE_LIB_CONFIG_MEM_ERR_CALLBACK	Two Arguments: *int (ProcMemError) (void ),* *void pUserData**	This option takes two arguments: a pointer to a client function which is invoked by the engine when running out-of-memory. The callback must take one argument which is an arbitrary user pointer. The second argument this option takes is the user pointer which is forwarded verbatim by the engine as the first argument to the callback. If the callback wishes to retry the failed memory allocation process it must return SXERR_RETRY. Note that running out-of-memory is an extremely unlikely scenario on modern hardware even on modern embedded system and so this option is not important as it might looks.
UNQLITE_LIB_CONFIG_USER_MUTEX	One Argument: *const SyMutexMethods pMethods**	This option takes a single argument which is a pointer to an instance of the SyMutexMethods structure. The argument specifies alternative low-level mutex routines to be used in place of the mutex routines built into UnQLite. Note that UnQLite will not make a private copy of the content of the SyMutexMethods structure which mean that the instance must be available during the life of the library.
UNQLITE_LIB_CONFIG_THREAD_LEVEL_SINGLE	No Arguments	This option sets the threading mode to Single-thread. In other words, mutexing is disabled and UnQLite is put in a mode where it can only be used by a single thread. This option have meaning only if UnQLite is compiled with the UNQLITE_ENABLE_THREADS directive enabled.
UNQLITE_LIB_CONFIG_THREAD_LEVEL_MULTI	No Arguments	This option sets the threading mode to Serialized. In other words, all mutexes are enabled including the recursive mutexes on database handles and Virtual Machine objects. This is the default mode when UnQLite is compiled with threading support via the UNQLITE_ENABLE_THREADS compile time directive.

The unqlite_lib_is_threadsafe() function returns TRUE (1) if and only if UnQLite was compiled with threading support enabled which is not the default behavior.

To compile UnQLite with threading support, simply define the UNQLITE_ENABLE_THREADS compile-time directive. Without multi-threading support (default case), it is not safe to use UnQLite concurrently from more than one thread.

Enabling mutexes incurs a measurable performance penalty. So if speed is of utmost importance, it makes sense to disable the mutexes.

unqlite_lib_version(), unqlite_lib_signature(), unqlite_lib_ident() and unqlite_lib_copyright() returns a pointer to a null terminated string holding respectively the current version of the UnQLite engine, the library signature, the library identification in the Symisc source tree and the copyright notice.

Return value

unqlite_lib_init(), unqlite_lib_shutdown() and unqlite_lib_config() returns UNQLITE_OK on success. Any other return value indicates failure.

unqlite_lib_version(), unqlite_lib_signature(), unqlite_lib_ident() and unqlite_lib_copyright() never fail and always return a pointer to a null terminated string.