Threads & The Scheduler

Discussion in 'Resources' started by Arkel, Sep 4, 2011.

Thread Status:
Not open for further replies.
  1. Offline


    Due to the influx of questions about threads and the scheduler in plugin development, I've created a short tutorial/FAQ, that is a bit more basic than the one on the wiki, that explains threads and the scheduler. If you can suggest any more questions, I'd be happy to add them.

    What is a thread?
    To understand this, think of a thread as a place where code goes to get executed. Most processors today have more than one core, and this allows them to do something called multi-threading - having more than one place where code can go to get executed. The result of this is the ability to run code that supports threading in a shorter timeframe; the code is split into smaller chunks that are run all at once rather than one after the other. But there are drawbacks too, threads can cause all sorts of problems if they aren't handled correctly. They're not just more difficult to write and debug, they can cause problems long down the line while your plugin is running. Any plugin you've written so far will have been executed in a single thread, the main server thread, this is the thread that handles server clock ticks, it aims to execute 20 times every second, sleeping at the end of each tick.

    What is the Bukkit scheduler?
    The bukkit scheduler is part of the Bukkit API that provides ways to schedule thread execution, either inside the main server thread (synchronous), or outside the main server thread (asynchronous/dedicated). It has three types of task that can be executed by each of these types of thread, these are 'Delayed', 'Repeating', and 'Tasks which return a value'. You MUST NOT CALL BUKKIT METHODS (apart from Scheduler methods, of course) FROM AN ASYNCHRONOUS/DEDICATED THREAD, see below for an explanation. There is only a single exception to this rule: world.getBlockTypeIdAt(int x, int y, int z). You must also avoid calling thread.wait() or sleep on the main thread (this should be obvious).

    How can I schedule a task/thread?
    This is actually very simple, get the Bukkit scheduler, using getServer().getScheduler(), and use highly self-explanatory methods it provides, for example, to schedule a synchronous delayed task:
    2. getServer().getScheduler().scheduleSyncDelayedTask(<YOUR_PLUGIN>, new Runnable() {
    3. public void run() {
    4. // Your code goes here
    5. }
    6. }, 60L); //This is the delay, in ticks, until the thread is executed, since the main threads ticks 20 times per second, 60 ticks is 3 seconds.

    Why can't I call Bukkit methods from outside the main thread?
    To put it bluntly, if both threads tried to interact with the same object at the same time, they could cause data corruption, this doesn't sound too bad, nor too likely, but on heavily used servers, your plugin could be corrupting anything from chunks to player's inventories.

    For further instruction, see, and
    knoxcorner and puyttre like this.
  2. Offline


    There's one thing that bugged me about this brief article:
    The three scheduling methods are two kinds of 'delayed', and then 'repeating'. I don't know what you mean by 'tasks which return a value'. A 'task' in this sense is nothing but a class that implements Runnable, and whose run() method is called at some point in time. Since run()'s return type is void, tasks can't 'return a value'. When you schedule a task, the scheduler returns to you an integer, which is the ID of the given task. You can use this later to cancel a scheduled task, but other than that it serves no purpose and doesn't mean anything.

    The three different scheduling methods are 1) 'delayed' without specifying a delay, which means the task will be executed ASAP (on the next tick), 2) 'delayed' with a given delay in server ticks, which delays the task for that many ticks, and 3) 'repeating', which delays the task for a given amount of ticks, and then repeats the task forever (or until cancelled) at a given interval.
    tha d0ctor likes this.
  3. Offline


    The following is quoted from the wiki:
Thread Status:
Not open for further replies.

Share This Page