Concurrency Model

PixelScript's threading model is designed to prioritize safe hot reloading, which has implications for how scripts interact with the Bukkit server thread. Understanding this model is crucial for writing efficient and safe PixelScript code.

Initial Evaluation

The initial evaluation of a script is always a blocking interaction in the main server thread. This means that as scripts look on boot or reload, they will execute synchronously on the main thread.

This is a design choice that ensures you can safely do your registration in your script on start, and is a critical security measure for listeners specifically. Blocking the main thread during a reload means that players cannot interact with the server while scripts are being reloaded. If you're reloading a script that prevents players from placing/breaking blocks, you don't want there to be a time window where the script is only partially reloaded and players can bypass those protections.

Same goes for initial startup, having script loading be synchronous means that the server is in a known state before players can join, where all scripts are fully loaded and you don't have any state races.

Platform Scheduler

The Scheduler API in PixelScript is lets you fully harness the underlying platform, which is usually Bukkit's scheduler. Generated code by scripts is thread-safe by default, meaning that each function may be executed concurrently unless you're manually synchronizing access to shared state.

"Syncronized" calls

Java has the Syncronized keyword, which allows you to mark methods or blocks of code as synchronized, meaning that only one thread can execute that code at a time.

PixelScript being a Java backed runtime, also gives you access to this functionality. You can use this functionality through the global Java object, like so:

Java.synchronized(function() {
    // critical section
}, objectToLockOn);

This will ensure that the critical section is only executed by one thread at a time, using the specified object as the lock. This is useful for protecting shared state that may be accessed by multiple threads, such as when using the Scheduler to run tasks asynchronously.