Added comments to ScriptEngine classes that explains what their purpose is

6 files changed, 68 insertions, 0 deletions

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.
+
+
     /// <summary>
     /// Contains all LSL ll-functions. This class will be in Default AppDomain.
     /// </summary>
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.
+        //
+
+
         /// <summary>
         /// List of threads processing event queue
         /// </summary>
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)
     /// </summary>
+    /// 
+
+    // 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
     {