Tweak thread safety and test dependency bleeding.

Author: Moderocky

src/main/java/org/byteskript/skript/api/SyntaxElement.java

@@ -25,16 +25,51 @@
 
 import static mx.kenzie.foundation.WriteInstruction.*;
 
+/**
+ * A syntax element.
+ * This instance controls the matching and compiling for a specific element.
+ * The library it comes from controls where it can be matched.
+ */
 public interface SyntaxElement {
 
+    /**
+     * Attempts to match this element to a source string.
+     * The context can be accessed, but should not be modified here.
+     * If the source does not match this element, return `null`.
+     * If the source does match this element, return a match object with the match data in.
+     * <p>
+     * Complex patterns are advised to override this and attempt faster
+     * checks with {@link String#contains(CharSequence)} before running the super matcher.
+     * This will circumvent a complex regex having to be checked every time.
+     *
+     * @param thing   the source
+     * @param context the context of this source
+     * @return the match result
+     */
     default Pattern.Match match(String thing, Context context) {
-        return getPattern().match(thing, context);
+        return this.getPattern().match(thing, context);
     }
 
+    /**
+     * The pattern metadata object.
+     *
+     * @return the pattern
+     */
     Pattern getPattern();
 
+    /**
+     * The library that provides this syntax element.
+     *
+     * @return the provider
+     */
     Library getProvider();
 
+    /**
+     * For basic syntax, this can return a method that will be used as a handle.
+     *
+     * @param type the handler mode
+     * @return the method handle
+     */
     Method getHandler(HandlerType type);
 
     void setHandler(HandlerType type, Method method);
@@ -60,14 +95,35 @@ default boolean allowAsInputFor(Type type) {
 
     boolean hasHandler(HandlerType type);
 
+    /**
+     * The return type of this element, used for type tracking during compilation.
+     *
+     * @return the return type
+     */
     default Type getReturnType() {
         return CommonTypes.VOID;
     }
 
+    /**
+     * This is called during the first compiler pass, Out->In, L->R.
+     * Simple elements will not need this, but lookahead or re-ordering operations can be run here.
+     *
+     * @param context the compiler context
+     * @param match   the match used
+     * @throws Throwable to avoid unnecessary try/catch blocks
+     */
     default void preCompile(Context context, Pattern.Match match) throws Throwable {
         // Very few elements require a lookahead.
     }
 
+    /**
+     * This is called during the second compiler pass, In->Out, L->R.
+     * Non-trivial syntax may need to override this to provide special behaviour.
+     *
+     * @param context the compiler context
+     * @param match   the match used
+     * @throws Throwable to avoid unnecessary try/catch blocks
+     */
     void compile(Context context, Pattern.Match match) throws Throwable;
 
     default boolean allowedIn(State state, Context context) {
@@ -86,6 +142,15 @@ default void addSkipInstruction(Context context, Consumer<Context> consumer) {
         context.addSkipInstruction(consumer);
     }
 
+    /**
+     * This writes a smart method call for the syntax, obeying rewrite rules.
+     * This can perform inlining, extraction and basic rewrites.
+     * This also has access to the bridge compiler.
+     *
+     * @param builder the method builder to use
+     * @param method  the target method
+     * @param context the compiler context
+     */
     default void writeCall(final MethodBuilder builder, final Method method, final Context context) {
         final ForceInline inline = method.getAnnotation(ForceInline.class);
         final ForceExtract extract = method.getAnnotation(ForceExtract.class);
@@ -133,6 +198,9 @@ default void writeCall(final MethodBuilder builder, final Method method, final C
         }
     }
 
+    /**
+     * A wrapped version of {@link Class#getMethod(String, Class[])} to avoid catching exceptions.
+     */
     default Method findMethod(Class<?> owner, String name, Class<?>... parameters) {
         try {
             return owner.getMethod(name, parameters);
@@ -168,7 +236,7 @@ default String name() {
 
     default String description() {
         final Documentation documentation = this.getClass().getAnnotation(Documentation.class);
-        if (documentation == null) return "None.";
+        if (documentation == null) return "No description.";
         return documentation.description();
     }
 
@@ -179,9 +247,7 @@ default String[] examples() {
     }
 
     class Handlers extends HashMap<HandlerType, Method> {
-        
-        public static final Handlers EMPTY = new Handlers();
-        
+    
     }
 
 }

src/main/java/org/byteskript/skript/api/syntax/Element.java

@@ -15,6 +15,9 @@
 import java.lang.reflect.Method;
 import java.util.Arrays;
 
+/**
+ * The basic syntax element class, which all existing syntax uses.
+ */
 public abstract class Element implements SyntaxElement {
 
     protected final Library provider;

src/main/java/org/byteskript/skript/runtime/Script.java

@@ -89,7 +89,7 @@ public Class<? extends CompiledScript> mainClass() {
     }
 
     void verify() {
-        this.forceLoad(mainClass());
+        this.forceLoad(this.mainClass());
         for (final Map.Entry<String, Member> entry : functions.entrySet()) {
             final Member value = entry.getValue();
             final String name = entry.getKey();

src/main/java/org/byteskript/skript/runtime/internal/Member.java

@@ -19,6 +19,11 @@
 import java.util.Collection;
 import java.util.concurrent.Future;
 
+/**
+ * A handle for a function, event, etc. inside a script.
+ * Keeping strong references to this is not advised, since it will prevent safe unloading.
+ * The member can be triggered safely from this.
+ */
 public class Member {
 
     protected final Script script;
@@ -123,10 +128,46 @@ public static MethodAccessor<Object> findFunction(Object owner, String name, Num
         return Mirror.of(owner).useProvider(Skript.findLoader()).method(name, parameters);
     }
 
+    /**
+     * Gets the script instance that provided this member.
+     *
+     * @return the owning script
+     */
     public Script getScript() {
         return script;
     }
 
+    /**
+     * Triggers this member in a new script thread.
+     * This will be run in the runtime from which the member was originally loaded.
+     *
+     * @param arguments the (function) arguments to pass
+     * @return a future governing this process
+     */
+    public Future<?> run(Object... arguments) {
+        final ScriptRunner runner = new ScriptRunner() {
+            @Override
+            public void start() {
+                invoker.invoke(arguments);
+            }
+            
+            @Override
+            public Class<? extends CompiledScript> owner() {
+                return script.mainClass();
+            }
+        };
+        return script.skriptInstance().runScript(runner);
+    }
+    
+    /**
+     * Triggers this member in a new script thread.
+     * This allows running in a different script runtime.
+     * This is potentially unsafe - alternative class versions can bleed between runtimes.
+     *
+     * @param skript    the Skript runtime
+     * @param arguments the (function) arguments to pass
+     * @return a future governing this process
+     */
     public Future<?> run(Skript skript, Object... arguments) {
         final ScriptRunner runner = new ScriptRunner() {
             @Override
@@ -142,6 +183,10 @@ public Class<? extends CompiledScript> owner() {
         return skript.runScript(runner);
     }
 
+    /**
+     * Triggers this member's verifier with a set of `null` parameters.
+     * Rather than returning a boolean result, this will throw an error if the verifier fails.
+     */
     public void verify() {
         if (verifier == null) return;
         verifier.invoke(new Object[parameters]);

src/test/java/org/byteskript/skript/test/ThreadingTest.java

@@ -16,13 +16,16 @@
 public class ThreadingTest extends SkriptTest {
 
     private static final Skript skript = new Skript();
+    private static final Skript skript2 = new Skript();
     private static Script script;
+    private static Script script2;
 
     @BeforeClass
     public static void start() throws Throwable {
         final PostCompileClass cls = skript.compileScript(ProvidedFunctionsTest.class.getClassLoader()
             .getResourceAsStream("flow.bsk"), "skript.flow");
         script = skript.loadScript(cls);
+        script2 = skript2.loadScript(cls);
     }
 
     @Test
@@ -32,4 +35,15 @@ public void sleep_test() throws Throwable {
         function.run(skript).get();
     }
 
+    @Test
+    public void multipleProcess() throws Throwable {
+        final Member function = script.getFunction("sleep_flow");
+        final Member function2 = script2.getFunction("sleep_flow");
+        function.run(skript).get();
+        function.run(skript2).get();
+        function2.run(skript2).get();
+        assert script.mainClass() != script2.mainClass();
+        assert script.skriptInstance() != script2.skriptInstance();
+    }
+    
 }