An Embeddable Scripting Engine |
Tweet |
Follow @jx9_engine |
Jx9 C/C++ API
Reference - List Of Constants.
This is a list of compile-time directives and numeric constants used by Jx9 and represented by #defines in the jx9.h header file. These constants are things such as numeric return parameters from various interfaces.
Result codes
Many Jx9 functions 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 Jx9.
| #define JX9_OK | /* Successful result */ | |
| #define JX9_NOMEM | /* Out of memory */ | |
| #define JX9_ABORT | /* Foreign Function request an operation abort/Another thread have released this instance */ | |
| #define JX9_IO_ERR | /* IO error */ | |
| #define JX9_LOOKED | /* Forbidden Operation */ | |
| #define JX9_CORRUPT | /* Corrupt pointer */ | |
| #define JX9_COMPILE_ERR | /* Compilation error */ | |
| #define JX9_VM_ERR | /* Virtual machine error */ |
The JX9_COMPILE_ERR and JX9_VM_ERR error codes are only returned by a call to one of the compile interfaces such as jx9_compile() or jx9_compile_file(). The first error code (JX9_COMPILE_ERR) is returned if there is a compile-time error while compiling the Jx9 script. In that case the caller must fix its erroneous Jx9 code and call the compile interface again. Note that the compile time error log can be extracted via a call to jx9_config() with a configuration verb set to JX9_CONFIG_ERR_LOG.
The second error code (JX9_VM_ERR) is returned if there is a problem related to the initialization of the Jx9 virtual machine (jx9_vm) after successful compilation of the target Jx9 script. This problem is generally due to a memory failure, but remember running out of memory is a very unlikely scenario on modern hardware even on modern embedded systems.
The JX9_IO_ERR is returned by a call to jx9_compile_file() only if an IO error occur (such as a nonexistent file or permission error) while opening the target file in read-only mode.
JX9_NOMEM is returned only if Jx9 is running out of memory. Again, this is an unlikely scenario on modern hardware.
JX9_ABORT can be returned from the body of an installed foreign function to stop program execution and thus to mimic the die construct. 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 jx9 or vm pointer have been released by another thread.
Compile-Time options for
The Jx9 Library
For most purposes, Jx9 can be built just fine using the default compilation options. However, if required, the compile-time options documented below can be used to omit Jx9 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.
JX9_ENABLE_THREADS
This option controls whether or not code is included in Jx9 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 Jx9 in a multithreaded program. When compiled with the JX9_ENABLE_THREADS directive enabled, Jx9 can be used in a multithreaded program and it's safe to share the same virtual machine and engine instance between two or more threads.
The value of JX9_ENABLE_THREADS can be determined at run-time using the jx9_lib_is_threadsafe() interface.
When Jx9 has been compiled with JX9_ENABLE_THREAD then the threading mode can be altered at run-time using the jx9_lib_config() interface together with one of these verbs:
Platforms others than Windows and UNIX systems must install their own mutex subsystem via jx9_lib_config() with a configuration verb set to JX9_LIB_CONFIG_USER_MUTEX. Otherwise the library is not threadsafe.
Note
that you must link Jx9 with the POSIX threads library under UNIX-like
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 Jx9 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.
JX9_DISABLE_BUILTIN_FUNC
JX9 come with more than 303 built-in functions suitable for most purposes ranging from string/INI processing to ZIP extracting, Base64 encoding/decoding, JSON encoding/decoding and so forth. If this directive is enabled, all built-in functions are omitted from the build. Note that special functions such as is_int(), is_string(), func_get_arg(), jx9_version(), etc. are not omitted from the build and are not affected by this directive.
JX9_ENABLE_MATH_FUNC
If this directive is enabled, built-in math functions such as sqrt(), abs(), log(), ceil(), etc. are included in the build. Note that you may need to link Jx9 with the math library in same Linux/BSD flavor (i.e: -lm).
JX9_DISABLE_DISK_IO
If this directive is enabled, built-in Virtual File System functions such as chdir(), mkdir(), chroot(), unlink(), sleep(), etc. are omitted from the build.
JX9_DISABLE_HASH_IO
If this directive is enabled, built-in hash functions such as md5(), sha1(), md5_file(), crc32(), etc. are omitted from the build.
JX9_OMIT_FLOATING_POINT (deprecated directive)
This option is used to omit floating-point arithmetic from the Jx9 library if compiling for a processor that lacks floating point support.
When specified, the library will substitute 64-bit integer for floating-point which mean that 25.e-3 and 25 are equals and are of type integer.
