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

Syntax

int vedis_lib_config(int nConfigOp,...);

int vedis_lib_init(void);

int vedis_lib_shutdown(void);

int vedis_lib_is_threadsafe(void);

const char * vedis_lib_version(void);

const char * vedis_lib_signature(void);

const char * vedis_lib_ident(void);

const char * vedis_lib_copyright(void);

Global Library Management Interfaces.

Description

The vedis_lib_init() routine initializes the vedis library. The vedis_lib_shutdown() routine deallocates any resources that were allocated by vedis_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 vedis normally do not need to invoke either of these routines.

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

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

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

The vedis_lib_init() interface is threadsafe, but vedis_lib_shutdown() is not. The vedis_lib_shutdown() interface must only be called from a single thread. This routine will take care of destroying any open database handle.

The vedis_lib_config() interface is used to make global configuration changes to vedis in order to tune vedis 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 vedis_lib_config() interface is not threadsafe. The application must insure that no other vedis interfaces are invoked by other threads while vedis_lib_config() is running. Furthermore, vedis_lib_config() may only be invoked prior to library initialization using vedis_lib_init() or after shutdown via vedis_lib_shutdown().

The first argument to vedis_lib_config() is an integer configuration option that determines what property of vedis 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
VEDIS_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.
VEDIS_LIB_CONFIG_STORAGE_ENGINE	One Argument: *vedis_kv_methods pKvEngine**	Install a foreign Key/Value storage engine. This option is reserved for future usage.
VEDIS_LIB_CONFIG_VFS	One Argument: *const vedis_vfs pVfs**	This option takes a single argument which is a pointer to an instance of the vedis_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 vedis will not make a private copy of the content of the vedis_vfs structure which mean that the instance must be available during the life of the library.
VEDIS_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 vedis. Note that vedis 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.
VEDIS_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.
VEDIS_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 vedis. Note that vedis 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.
VEDIS_LIB_CONFIG_THREAD_LEVEL_SINGLE	No Arguments	This option sets the threading mode to Single-thread. In other words, mutexing is disabled and vedis is put in a mode where it can only be used by a single thread. This option have meaning only if vedis is compiled with the VEDIS_ENABLE_THREADS directive enabled.
VEDIS_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. This is the default mode when vedis is compiled with threading support via the VEDIS_ENABLE_THREADS compile time directive.

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

To compile vedis with threading support, simply define the VEDIS_ENABLE_THREADS compile-time directive. Without multi-threading support (default case), it is not safe to use vedis 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.

vedis_lib_version(), vedis_lib_signature(), vedis_lib_ident() and vedis_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

vedis_lib_init(), vedis_lib_shutdown() and vedis_lib_config() returns VEDIS_OK on success. Any other return value indicates failure.

vedis_lib_version(), vedis_lib_signature(), vedis_lib_ident() and vedis_lib_copyright() never fail and always return a pointer to a null terminated string.