captainspauldings/ams-doc

AMS Documentation

Advanced Management System

AMS Wiki
AMS Source code (private)
AMS Discussion (private)
AMS Open Issues (private)
AMS Closed Issues (private)

DESCRIPTION

AMS is a Lua library package for FlyWithLua.
It allows a precise control over the tasks called at each loop and provides additional integration with X-Plane SDK.

 
 

MAIN FEATURES

• LOCAL VS. GLOBAL

FlyWithLua's architecture limits the uses of local functions, because all the callbacks need to have the functions on the global scope.
AMS, on the other hand, has been designed to allow the use of local functions for the callbacks, avoiding any conflict between the scripts.  
 

• PREEMPTIVE TASK CONTROL

AMS implements a task management that allows one to pause, resume and kill each running process.
A task can even kill and pause itself, or move from a loop to another.  
 

• PROTECTED CALLS

AMS tasks are executed as protected calls, thus every error generated by the called process doesn't stop the interpreter.
When a task generates a certain amount of consecutive errors, that can be set by the user, the process gets automatically killed. All the error messages are reported in the log file.  
 

• TIMERS

AMS takes track of the CPU usage of every task, giving information on the average and peak speed as well as the real-time value.
This is useful to monitor the performance of the running processes and make a better optimization.  
 

• DATAREF MANAGER

AMS implements a system to take track of the datarefs' access requested by the scripts, to avoid duplicate access for the ones used by multiple scripts. It also takes care of making the custom defined datarefs and commandrefs visible to DatarefTool.  
 

• QUARANTINE-FREE LOADER

FlyWithLua adopted the quarantine mechanism to detect and remove faulty scripts. This system, though, has some side effects, such as moving the faulty script outside the Script directory as well as having issues related to false-positives. AMS provides an alternative scripts loader that detects faulty scripts, reporting the error encountered in the log file, without moving it.
All the scripts are loaded in protected mode, so the eventual errors on the script don't stop the interpreter.  
 

• KICKSTARTER

AMS can install its Kickstarter to get automatically loaded upon FlyWithLua startup.
This allows AMS to take control of all the scripts available, not only the ones that explicitly require it, tracking their performance and dataref usage.  
 

• DEDICATED LOG FILE

AMS can divert all the output messages to a dedicated log file called AMS_debug.log that can be found in X-Plane's main dir. This makes it easier to browse the log and check for error messages.
AMS's logger will take care of automatically inserting the timestamp and the name of the script at the beginning of each entry in the file.

 
 

BLOCK DIAGRAM

AMS lays on top of FlyWithLua to get access to X-Plane SDK; it also implements it's own SDK wrapper to add functions missing in FlyWithLua.

The following is the block diagram of AMS used just as packages, called by the scripts that need it, and used with Kickstarter, where AMS takes control of all the installed scripts.