Falcon Wiki - Embedders guide
The manual is (currently being) updated with Falcon 0.9.4 (Eagle). We're writing it from the ground up right now, so it will take some time to be completed; sorry for the distress.
Falcon has been designed to run in any C++ application. It is possible to use the ready-to-use classes to load code and run it, or to extend them to perform more specific work or carry around more specific data.
For example, an embedding application may just load pre-compiled code from mass storage, network or memory through the ModuleLoader class. With the support of a Runtime class, the embedder may be able to load iteratively the components referenced in the loaded module. Using a FlcModuleLoader, which provides a source compiler, it will be possible to load existing scripts from disk, or search pre-compiled versions automatically. Alternatively, the embedder may use the Compiler class and feed it with a source, then resolve and load the needed dependencies as needed.
When the best way for the application to load the module(s) has been setup, all that's needed is to feed the Runtime holding the modules into a VMachine object and let it run.
Usually, an application won't just need to load and run scripts; it will have to provide the application with data in order to recieve the its results.
If needs are simple, this can be easily achieved by pushing variables into the virtual machine before starting execution, and retrieving the values after execution completion.
When the needs are more sophisticated, it is advisable to write an application specific module which will provide constants, functions, object and classes through which the script can call application routines. There isn't any need to create a separate loadable module (dll/so/dynlib or what else), as the application may create a Module object and feed it directly into the virtual machine.
When things gets really nasty, it is possible to override the Virtual Machine and/or the module loader(s) to perform specific tasks. For example, by overriding the module loader it will be possible to search the scripts in a database or on a network instead of the file system. As all the C/C++ functions called directly from the scripts are provided with the calling VM, it would be possible to override the VM to provide application specific functions with more data, i.e. backpointers to application specific structures or script specific data.
Another script-to-application communication mechanism is the suspend() call. Scripts can call the suspend() function that will terminate, temporarily, VM execution. The application can restart the script and have the suspend() function to return a specific value by calling the VMachine::resume() method.
Let me dedicate the last paragraphs of these forewords to multithreading. Falcon internals are completely threadsafe, in the sense that the same module can be safely run into two different virtual machine from two different threads. There isn't any need of synchronization between threads using Falcon virtual machines (except for loading and disposing of the module). However, a single virtual machine is not threadsafe in itself; each virtual machine must be run in its own thread, and care must be taken to avoid controlling a virtual machine from different threads. Data can be shared across virtual machines running in different threads, but this operation requires some care that will be described in a specific chapter.
- Build environment
- The basics
- Application module
- Structure sharing
- Script Callbacks
- Using the Falcon Engine in a multithreaded embedded application
- Advanced topics