PcoWSkbVqDnWTu_dm2ix
Collapse Sidebar

task

The task library offers alternatives to various global functions (wait, spawn and delay) that allow better coordination with the articles/Task Scheduler.

The functions available in this library generally work with both functions and threads as returned by coroutine.create. It’s recommended you familiarize yourself with the coroutine library.

void task.spawn ( function functionOrThread, Variant ... )

Accepts a function or a thread (as returned by coroutine.create) and calls/resumes it immediately through the engine’s scheduler. Arguments after the first are sent to the function/thread. This function does not return any value, even if the provided function returns one immediately.

This function is based on the fastSpawn pattern rather than being a replacement for the global spawn function. It is recommended that this function be used in place of fastSpawn.


Usage of task.spawn

This code sample demonstrates a use case of task.spawn wherein a function is being called while iterating over a set of objects. In particular, the playerAdded function is called for all existing Player objects. Although the function yields, doing so does not prevent the continued iteration over the rest of the existing players as the function call was made through task.spawn.

void task.defer ( function functionOrThread, Variant ... )

Accepts a function or a thread (as returned by coroutine.create) and defers it until the next resumption cycle, at which point it is resumed with the engine’s scheduler like with task.spawn. Arguments after the first are sent to the function/thread. This function does not return any value, even if the provided function returns one immediately.

This function should be used when a similar behavior to task.spawn is desirable, but the thread does not need to run immediately.


task.defer Example

This code sample demonstrates how task.defer calls a function later at the next resumption cycle.

void task.delay ( number duration, function functionOrThread, Variant ... )

Accepts a function or a thread (as returned by coroutine.create) and schedules it to be called/resumed on the next RunService/Heartbeat|Heartbeat after the given amount of time in seconds has elapsed. Arguments after the second are sent to the function/thread.

This function differs from the global delay function in that no throttling occurs: on the very same Heartbeat step in which enough time has passed, the function is guaranteed to be called/resumed. Providing a duration of zero (0) will guarantee that the function is called on the very next Heartbeat.

You can calculate the actual time passed by calling os.clock upon scheduling and in the scheduled function.


task.delay Actual Time

This code sample demonstrates how you can calculate the actual time passed when a function sent to task.delay is called. Using os.clock(), you can send the scheduled function the time in which it was scheduled, then calculate the difference by calling it again.

number task.wait ( number duration = 0 )

Yields the current thread until the given duration (in seconds) has elapsed, then resumes the thread on the next RunService/Heartbeat|Heartbeat step. The actual amount of time elapsed is returned.

If no duration is given, it will default to zero (0). This means the thread resumes on the very next step, which is equivalent in behavior to RunService.Heartbeat:Wait()

Unlike the global wait, this function does not throttle and guarantees the resumption of the thread on the first Heartbeat that occurs when it is due. This function also only returns the elapsed time and nothing else.