server.scheduler

fn new_closure_task(cb fn ()) &ClosureTask

new_closure_task wraps cb in a Task.

fn new_scheduler() &Scheduler

interface Task {
	run()
}

Task is scheduled work run synchronously on the server's global tick thread. Implement run() with the work to perform when the task fires.

Tasks must remain short and non-blocking: a slow task delays the global tick cadence for every world. Schedule world specific work through that World's scheduler instead. For simple one off callbacks, use ClosureTask.

struct ClosureTask {
	callback fn () @[required]
}

ClosureTask adapts a plain function into a Task so callers can schedule a closure without declaring a struct.

fn (t &ClosureTask) run()

struct Scheduler {
mut:
	mutex        &sync.Mutex = sync.new_mutex()
	tasks        map[int]&TaskHandler
	current_tick i64
	next_id      int = 1
}

Scheduler runs Tasks against the server tick clock. Tasks may be scheduled from session threads while heartbeat() runs on the tick thread. A mutex guards the task table; tasks themselves run outside the lock so a task may safely schedule more work.

See Task's own doc comment for exactly where and how run() executes. synchronously on the single global tick thread, not a per-world or per-task thread.

fn (mut s Scheduler) run_task(task Task) &TaskHandler

run_task queues task to run on the next tick.

fn (mut s Scheduler) run_delayed(task Task, delay i64) &TaskHandler

run_delayed queues task to run once, delay ticks from now.

fn (mut s Scheduler) run_repeating(task Task, period i64) &TaskHandler

run_repeating queues task to run every period ticks, starting next tick.

fn (mut s Scheduler) run_delayed_repeating(task Task, delay i64, period i64) &TaskHandler

run_delayed_repeating queues task to first run after delay ticks, then every period ticks.

fn (mut s Scheduler) cancel(id int)

cancel stops and removes the task with the given id, if present.

fn (mut s Scheduler) cancel_all()

cancel_all cancels and drops every queued task.

fn (mut s Scheduler) count() int

count reports how many tasks are queued.

fn (mut s Scheduler) heartbeat(tick i64)

heartbeat advances the clock to tick and runs every task due at or before it. Called once per server tick from the tick actor thread. Due tasks are collected under the lock, then run unlocked; repeating tasks are rescheduled and one-shots removed afterwards.

struct TaskHandler {
	id     int
	delay  i64
	period i64
mut:
	task      Task
	next_run  i64
	cancelled bool
}

TaskHandler is the scheduler's live record of a queued task. It is returned from every schedule_* call so the caller can cancel the task later. delay and period are in ticks; next_run is the tick the task fires on.

fn (h &TaskHandler) id() int

id returns the scheduler-assigned handle id.

fn (h &TaskHandler) is_cancelled() bool

is_cancelled reports whether the task has been cancelled.

fn (mut h TaskHandler) cancel()

cancel stops the task from running again. A repeating task will not fire after this; a pending delayed task never fires.

fn (h &TaskHandler) is_repeating() bool

is_repeating reports whether the task reschedules itself after each run.