From 7ef09a12020f1665bcd4e99fd420d411d5f4d95d Mon Sep 17 00:00:00 2001 From: Tedd Hansen Date: Sun, 30 Dec 2007 16:32:29 +0000 Subject: Added comments to ScriptEngine classes that explains what their purpose is --- .../Common/LSL_BuiltIn_Commands_Interface.cs | 3 +++ .../DotNetEngine/Compiler/LSL/Compiler.cs | 8 ++++++++ .../DotNetEngine/Compiler/LSL/LSL_BaseClass.cs | 8 ++++++++ .../Compiler/Server_API/LSL_BuiltIn_Commands.cs | 6 ++++++ .../ScriptEngine/DotNetEngine/EventManager.cs | 13 +++++++++++++ .../ScriptEngine/DotNetEngine/EventQueueManager.cs | 22 ++++++++++++++++++++++ .../ScriptEngine/DotNetEngine/ScriptManager.cs | 11 +++++++++++ 7 files changed, 71 insertions(+) (limited to 'OpenSim') diff --git a/OpenSim/Region/ScriptEngine/Common/LSL_BuiltIn_Commands_Interface.cs b/OpenSim/Region/ScriptEngine/Common/LSL_BuiltIn_Commands_Interface.cs index 9c595ed..b4e68cd 100644 --- a/OpenSim/Region/ScriptEngine/Common/LSL_BuiltIn_Commands_Interface.cs +++ b/OpenSim/Region/ScriptEngine/Common/LSL_BuiltIn_Commands_Interface.cs @@ -32,6 +32,9 @@ namespace OpenSim.Region.ScriptEngine.Common { public interface LSL_BuiltIn_Commands_Interface { + + // Interface used for loading and executing scripts + string State(); double llSin(double f); diff --git a/OpenSim/Region/ScriptEngine/DotNetEngine/Compiler/LSL/Compiler.cs b/OpenSim/Region/ScriptEngine/DotNetEngine/Compiler/LSL/Compiler.cs index 0623cc5..441c952 100644 --- a/OpenSim/Region/ScriptEngine/DotNetEngine/Compiler/LSL/Compiler.cs +++ b/OpenSim/Region/ScriptEngine/DotNetEngine/Compiler/LSL/Compiler.cs @@ -36,6 +36,14 @@ namespace OpenSim.Region.ScriptEngine.DotNetEngine.Compiler.LSL { public class Compiler { + + // * Uses "LSL2Converter" to convert LSL to C# if necessary. + // * Compiles C#-code into an assembly + // * Returns assembly name ready for AppDomain load. + // + // Assembly is compiled using LSL_BaseClass as base. Look at debug C# code file created when LSL script is compiled for full details. + // + private LSL2CSConverter LSL_Converter = new LSL2CSConverter(); private CSharpCodeProvider codeProvider = new CSharpCodeProvider(); private static UInt64 scriptCompileCounter = 0; diff --git a/OpenSim/Region/ScriptEngine/DotNetEngine/Compiler/LSL/LSL_BaseClass.cs b/OpenSim/Region/ScriptEngine/DotNetEngine/Compiler/LSL/LSL_BaseClass.cs index 2796b64..65db510 100644 --- a/OpenSim/Region/ScriptEngine/DotNetEngine/Compiler/LSL/LSL_BaseClass.cs +++ b/OpenSim/Region/ScriptEngine/DotNetEngine/Compiler/LSL/LSL_BaseClass.cs @@ -41,6 +41,14 @@ namespace OpenSim.Region.ScriptEngine.DotNetEngine.Compiler.LSL //[Serializable] public class LSL_BaseClass : MarshalByRefObject, LSL_BuiltIn_Commands_Interface, IScript { + + // + // Included as base for any LSL-script that is compiled. + // Any function added here will be accessible to the LSL script. But it must also be added to "LSL_BuiltIn_Commands_Interface" in "OpenSim.Region.ScriptEngine.Common" class. + // + // Security note: This script will be running inside an restricted AppDomain. Currently AppDomain is not very restricted.zxs + // + // Object never expires public override Object InitializeLifetimeService() { diff --git a/OpenSim/Region/ScriptEngine/DotNetEngine/Compiler/Server_API/LSL_BuiltIn_Commands.cs b/OpenSim/Region/ScriptEngine/DotNetEngine/Compiler/Server_API/LSL_BuiltIn_Commands.cs index d5a31fb..e6a9fe2 100644 --- a/OpenSim/Region/ScriptEngine/DotNetEngine/Compiler/Server_API/LSL_BuiltIn_Commands.cs +++ b/OpenSim/Region/ScriptEngine/DotNetEngine/Compiler/Server_API/LSL_BuiltIn_Commands.cs @@ -47,6 +47,12 @@ namespace OpenSim.Region.ScriptEngine.DotNetEngine.Compiler // REMEMBER TO UPDATE http://opensimulator.org/wiki/LlFunction_implementation_status // + // Notes: + // * If any function here needs to execute a LSL event in the script, use instance of "EventQueueManager" in "ScriptEngine". + // * If any function here needs to do some more advanced stuff like waiting for IO callbacks or similar that takes a long time then use "llSetTimerEvent" function as example. + // There is a class called "LSLLongCmdHandler" that is used for long LSL commands. + + /// /// Contains all LSL ll-functions. This class will be in Default AppDomain. /// diff --git a/OpenSim/Region/ScriptEngine/DotNetEngine/EventManager.cs b/OpenSim/Region/ScriptEngine/DotNetEngine/EventManager.cs index 8dfd908..ced5025 100644 --- a/OpenSim/Region/ScriptEngine/DotNetEngine/EventManager.cs +++ b/OpenSim/Region/ScriptEngine/DotNetEngine/EventManager.cs @@ -38,6 +38,19 @@ namespace OpenSim.Region.ScriptEngine.DotNetEngine [Serializable] internal class EventManager { + + // + // Class is instanced in "ScriptEngine" and Uses "EventQueueManager" that is also instanced in "ScriptEngine". + // This class needs a bit of explaining: + // + // This class it the link between an event inside OpenSim and the corresponding event in a user script being executed. + // + // For example when an user touches an object then the "myScriptEngine.World.EventManager.OnObjectGrab" event is fired inside OpenSim. + // We hook up to this event and queue a touch_start in EventQueueManager with the proper LSL parameters. It will then be delivered to the script by EventQueueManager. + // You can check debug C# dump of an LSL script if you need to verify what exact parameters are needed. + // + + private ScriptEngine myScriptEngine; //public IScriptHost TEMP_OBJECT_ID; public EventManager(ScriptEngine _ScriptEngine) diff --git a/OpenSim/Region/ScriptEngine/DotNetEngine/EventQueueManager.cs b/OpenSim/Region/ScriptEngine/DotNetEngine/EventQueueManager.cs index 2d0d69d..e2b11cc 100644 --- a/OpenSim/Region/ScriptEngine/DotNetEngine/EventQueueManager.cs +++ b/OpenSim/Region/ScriptEngine/DotNetEngine/EventQueueManager.cs @@ -44,6 +44,28 @@ namespace OpenSim.Region.ScriptEngine.DotNetEngine [Serializable] internal class EventQueueManager { + + // + // Class is instanced in "ScriptEngine" and used by "EventManager" also instanced in "ScriptEngine". + // + // Class purpose is to queue and execute functions that are received by "EventManager": + // - allowing "EventManager" to release its event thread immediately, thus not interrupting server execution. + // - allowing us to prioritize and control execution of script functions. + // Class can use multiple threads for simultaneous execution. Mutexes are used for thread safety. + // + // 1. Hold an execution queue for scripts + // 2. Use threads to process queue, each thread executes one script function on each pass. + // 3. Catch any script error and process it + // + // + // Notes: + // * Current execution load balancing is optimized for 1 thread, and can cause unfair execute balancing between scripts. + // Not noticeable unless server is under high load. + // * This class contains the number of threads used for script executions. Since we are not microthreading scripts yet, + // increase number of threads to allow more concurrent script executions in OpenSim. + // + + /// /// List of threads processing event queue /// diff --git a/OpenSim/Region/ScriptEngine/DotNetEngine/ScriptManager.cs b/OpenSim/Region/ScriptEngine/DotNetEngine/ScriptManager.cs index e211902..ac378ae 100644 --- a/OpenSim/Region/ScriptEngine/DotNetEngine/ScriptManager.cs +++ b/OpenSim/Region/ScriptEngine/DotNetEngine/ScriptManager.cs @@ -45,6 +45,17 @@ namespace OpenSim.Region.ScriptEngine.DotNetEngine /// Compiles them if necessary /// Execute functions for EventQueueManager (Sends them to script on other AppDomain for execution) /// + /// + + // This class is as close as you get to the script without being inside script class. It handles all the dirty work for other classes. + // * Keeps track of running scripts + // * Compiles script if necessary (through "Compiler") + // * Loads script (through "AppDomainManager" called from for example "EventQueueManager") + // * Executes functions inside script (called from for example "EventQueueManager" class) + // * Unloads script (through "AppDomainManager" called from for example "EventQueueManager") + // * Dedicated load/unload thread, and queues loading/unloading. + // This so that scripts starting or stopping will not slow down other theads or whole system. + // [Serializable] public class ScriptManager { -- cgit v1.1