Implementation notes for Scripting support in the API
-----------------------------------------------------
The script-related classes are designed to support multiple different
scripting implementations - either separate languages, or multiple
versions of a single language.
Implementation details are hidden from callers with a combination of
the C++ PIMPL idiom (so header includes don't leak symbols - see
p4script.h), symbol redefinition (keeping the language runtime symbols
unique, preventing clash with customer programs and other versions of
the runtime - see p4script53_redefines.h) and using a single
compilation unit. There are alternative approaches such as using
anonymous namespaces (to force internal linkage) or linker tools to
hide/rename symbols (e.g. using objcopy). There are issues with
putting headers or libraries into separate namespaces, so that's not
recommended. Note that luaconf.h has some provisions for controling
visibility as well.
Note that there are no references to Lua datatypes or signatures in
p4script.h so as not to require any of that for API users. Functions
taking Lua datatypes as arguments use void* and casts.
Testing for symbol clash can be done by copying the existing script
implementation file and its symbol redefinition header into new files and
giving them new names - when building with the new files in LTO mode, you
would expect to see conflicts there it there are any. One can also take
the library and link it to a sample program that uses the un-prefixed
versions of the 3rd-party code.
Lua itself is C code, but is compiled here as C++ so as to support
exceptions (which Sol can throw when something goes wrong - e.g. a
script returns the wrong datatype to a C++ function). Lua compiled
as C uses longjmp when an error happens, and that isn't compatible
with exceptions or the stack unwinding necessary to call any bound C++
classes' destructors.
A consequence of Lua being built as C++ is that any native libraries
extending Lua (e.g. LuaSQLite) must be built as C++ so they can link
properly. Lua-extending native libraries can however call down into
C, so that direction does not require any special consideration (e.g.
the LuaSQLite case where LuaSQLite needs to be C++ to talk with our
C++ copy of Lua, but itself then talks with the C-built SQLite.)
The 'lua-5.3' subdirectory omits the patch level since they're assumed
to be minor changes, not introducing incompatibilities.
The 'sol2' library provides a variety of mechanisms for bridging the
Lua/C++ gap.
http://sol2.readthedocs.io/
The P4API classes are generally bound to Lua via C++ subclasses via
shared function pointers that Lua code can assign to.
There are some edits to the Lua source in support of various properties
we need (e.g. not doing blocking operations that we can't interrupt when
enforcing Max* limits). Changes are:
- the os.execute() edit in loslib.c.