Symisc Systems

Libcox C/C++ API Reference - Global Library Management Interfaces


Star Follow @symisc

Syntax

int libcox_lib_config(int nConfigOp,...);

int libcox_lib_init(void);

int libcox_lib_shutdown(void);

int libcox_lib_is_threadsafe(void);

const char * libcox_lib_version(void);

const char * libcox_lib_signature(void);

const char * libcox_lib_ident(void);

const char * libcox_lib_copyright(void);


Global Library Management Interfaces.

Description

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

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

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

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

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

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

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

Configuration Options

Expected Arguments

Description

LIBCOX_LIB_CONFIG_VFS

One Argument:
const libcox_vfs *pVfs

This option takes a single argument which is a pointer to an instance of the libcox_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 libcox will not make a private copy of the content of the libcox_vfs structure which mean that the instance must be available during the life of the library.

LIBCOX_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 libcox. Note that libcox 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.

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

LIBCOX_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 libcox. Note that libcox 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.

LIBCOX_LIB_CONFIG_THREAD_LEVEL_SINGLE

No Arguments

This option sets the threading mode to Single-thread. In other words, mutexing is disabled and libcox is put in a mode where it can only be used by a single thread. This option have meaning only if libcox is compiled with the LIBCOX_ENABLE_THREADS directive enabled.

LIBCOX_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 the libcox handles. This is the default mode when libcox is compiled with threading support via the LIBCOX_ENABLE_THREADS compile time directive.


The libcox_lib_is_threadsafe() function returns TRUE (1) if and only if libcox was compiled with threading support enabled which is not the default behaviour.

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

libcox_lib_version(), libcox_lib_signature(), libcox_lib_ident() and libcox_lib_copyright() returns a pointer to a null terminated string holding respectively the current version of the Libcox engine, the library signature, the library identification in the Symisc source tree and the copyright notice.


Return value

libcox_lib_init(), libcox_lib_shutdown() and libcox_lib_config() returns LIBCOX_OK on success. Any other return value indicates failure.
libcox_lib_version(), libcox_lib_signature(), libcox_lib_ident() and libcox_lib_copyright() never fail and always return a pointer to a null terminated string.