Hey developers,
We have just enabled a brand new library that you can use in your projects. The task library allows you to talk directly with our engine’s task scheduler to manage and schedule code. It features a number of new methods as well as some improvements to existing methods.
Details
task.spawn
Takes a thread or function and resumes it immediately through the engine’s scheduler. Additional arguments are passed to the thread or function being resumed.
void task.spawn(function | thread, ...args)
This is particularly useful when calling a function which may yield when iterating over a set of objects:
local function playerAdded(player)
...
(yield)
end
for _, player in ipairs(Players:GetPlayers()) do
task.spawn(playerAdded, player)
end
task.spawn is based on the fastSpawn pattern rather than being a replacement for spawn. We recommend you use this method where you would otherwise use fastSpawn.
task.defer
Takes a thread or function and defers it until the next resumption cycle at which point it is resumed with the engine’s scheduler. Additional arguments are passed to the thread or function being resumed.
void task.defer(function | thread, ...args)
You should typically use this when you want similar behavior to task.spawn but don’t care about the thread running immediately.
task.defer(print, "A")
print("B")
--> B
--> A
task.defer is an improved version of spawn which schedules a thread to be resumed as soon as possible (but not immediately) without any throttling.
task.delay
Takes a thread or function and schedules it for resumption after the given amount of time has elapsed on the next Heartbeat step. The thread is resumed with built-in error handling and support for other engine features. Any additional arguments are passed to the thread or function being resumed.
void task.delay(duration, function | thread, ...args)
Since the actual delay time may vary it can be calculated by passing the current time as an argument.
task.delay(2, function (scheduledTime)
print(os.clock() - scheduledTime) --> 2.038702
end, os.clock())
A duration of zero will result in the thread or function being resumed on the next step.
task.delay is an improved version of delay which schedules a thread to be resumed after some time has elapsed without throttling.
task.wait
Yields the current thread until the given duration (in seconds) has elapsed and then resumes the thread on the next Heartbeat step.
elapsed task.wait(duration=0)
Since the actual yield time may vary, this method returns it for convenience.
local elapsedTime = task.wait(2) -- wait for 2 seconds
print(elapsedTime) --> 2.0792941
If no duration is given the duration will default to zero meaning the thread will automatically resume on the next step.
task.wait()
-- is equivalent in behavior to
RunService.Heartbeat:Wait()
task.wait is an improved version of wait which schedules the current thread to be resumed after some time has elapsed without throttling.
Existing Methods
We will eventually mark the existing methods (spawn, delay, and wait) as deprecated in favor of their alternatives however they will continue to work as they do now for the foreseeable future and we have no plans to change this.
the improved versions of old functions that were particularly discouraged (e.g. delay), especially wait and how it’s based on Heartbeat frequency. Don’t have to write my own boilerplate for that anymore or abuse Promises to get what I need. Same goes with task.spawn for fastSpawn. Less boilerplate and I can use these better versions rather than the ones based on the old frequencies.