An Embeddable Datastore Engine

Tweet

Follow @Vedis

This is a list of compile-time directives and numeric constants used by Vedis and represented by #defines in the vedis.h header file. These constants are things such as numeric return parameters from various interfaces.

Result codes

Most of the vedis public interfaces return an integer result code from the set shown here in order to indicates success or failure. New error codes may be added in future versions of vedis.

/* Standard vedis return values */

#define VEDIS_OK               /* Successful result */

/* Beginning of error codes */

#define VEDIS_NOMEM            /* Out of memory */

#define VEDIS_ABORT            /* Another thread have released this instance */

#define VEDIS_IOERR            /* IO error */

#define VEDIS_CORRUPT          /* Corrupt pointer */

#define VEDIS_LOCKED           /* Forbidden Operation */

#define VEDIS_BUSY             /* The database file is locked */

#define VEDIS_DONE             /* Operation done */

#define VEDIS_PERM             /* Permission error */

#define VEDIS_NOTIMPLEMENTED   /* Method not implemented by the underlying Key/Value storage engine */

#define VEDIS_NOTFOUND         /* No such record */

#define VEDIS_NOOP             /* No such method */

#define VEDIS_INVALID          /* Invalid parameter */

#define VEDIS_EOF              /* End Of Input */

#define VEDIS_UNKNOWN          /* Unknown command */

#define VEDIS_LIMIT            /* Database limit reached */

#define VEDIS_EXISTS           /* Records exists */

#define VEDIS_EMPTY            /* Empty record */

#define VEDIS_COMPILE_ERR      /* Compilation error */

#define VEDIS_VM_ERR           /* Virtual machine error */

#define VEDIS_FULL             /* Full database (unlikely) */

#define VEDIS_CANTOPEN         /* Unable to open the database file */

#define VEDIS_READ_ONLY        /* Read only Key/Value storage engine */

#define VEDIS_LOCKERR          /* Locking protocol error */

VEDIS_OK indicates successful result. Any other return value indicates failure and the caller should handle the error. For a human-readable error message, the client can extract the database error log via vedis_config() with a configuration verb set to VEDIS_CONFIG_ERR_LOG.

VEDIS_UNKNOWN is returned when a unknown command is encountered while executing user script via vedis_exec(). Refer to the following document for the list of implemented commands.

VEDIS_READ_ONLY is returned when the underlying Key/Value storage engine only support read-only operations or the database was opened with read-only privileges.

VEDIS_BUSY is returned when another thread or process have a reserved or exclusive lock on the database. In which case, the caller should wait until the lock holder relinquish it. Many public interfaces return this error code such as: vedis_kv_store(), vedis_kv_append(), vedis_kv_delete() and so forth.

VEDIS_NOTIMPLEMENTED is returned when the underlying KV storage engine does not implement the target method. For example, the xAppend() method for vedis_kv_append(), xStore() for vedis_kv_store(), xDelete() for vedis_kv_delete() and so forth.

VEDIS_NOMEM is returned when Vedis is running out of memory. Again, this is a unlikely scenario on modern hardware.

VEDIS_ABORT can be returned from the body of an installed foreign command to stop program execution . This error code can also be returned from one of the public interfaces if and only if the library was compiled with threading support and the given vedis pointer have been released by another thread.

Compile-Time options for The vedis Library

For most purposes, Vedis can be built just fine using the default compilation options. However, if required, the compile-time options documented below can be used to omit vedis features (resulting in a smaller compiled library size) or to change the default values of some parameters.

Every effort has been made to ensure that the various combinations of compilation options work harmoniously and produce a working library.

VEDIS_ENABLE_THREADS

This option controls whether or not code is included in Vedis to enable it to operate safely in a multithreaded environment. The default is not. All mutexing code is omitted and it is unsafe to use vedis in a multithreaded program. When compiled with the VEDIS_ENABLE_THREADS directive enabled, Vedis can be used in a multithreaded program and it is safe to share the same datastore handle between two or more threads.

The value of VEDIS_ENABLE_THREADS can be determined at run-time using the vedis_lib_is_threadsafe() interface.

When Vedis has been compiled with threading support then the threading mode can be altered at run-time using the vedis_lib_config() interface together with one of these verbs:

VEDIS_LIB_CONFIG_THREAD_LEVEL_SINGLE

VEDIS_LIB_CONFIG_THREAD_LEVEL_MULTI

Platforms others than Windows and UNIX systems must install their own mutex subsystem via vedis_lib_config() with a configuration verb set to VEDIS_LIB_CONFIG_USER_MUTEX. Otherwise the library is not threadsafe.

Note that you must link vedis with the POSIX threads library under UNIX systems (i.e: -lpthread).

Options To Omit/Enable Features

The following options can be used to reduce the size of the compiled library by omitting optional features. This is probably only useful in embedded systems where space is especially tight, as even with all features included the vedis library is relatively small. Don't forget to tell your compiler to optimize for binary size! (the -Os option if using GCC). Telling your compiler to optimize for size usually has a much larger impact on library footprint than employing any of these compile-time options.

VEDIS_ENABLE_HASH_CMD

If this directive is enabled, built-in hash commands such as MD5, SHA1, CRC32, etc. are included in the build.