Skip to main content

Handle

A reference to a single scheduled task, returned by Scope scheduling methods.

Use a Handle to cancel, pause, resume, or reconfigure a task after scheduling. A Handle becomes invalid when :cancel() is called or when the parent Scope is destroyed. Calling any method on an invalid Handle throws an error. 

local handle = scope:every(5, function()
	print("tick")
end)

handle:pause()
handle:setInterval(10)
handle:resume()
handle:cancel()

Functions​

cancel​

</>
Handle.cancel(self: HandleInternal) → ()

Removes this task from the schedule permanently. The Handle becomes invalid immediately and cannot be paused, resumed, or cancelled again.

Errors

TypeDescription
"Handle is already cancelled"Thrown if called on an already-cancelled Handle.
"Parent scope is destroyed"Thrown if the parent Scope was destroyed.

pause​

</>
Handle.pause(self: HandleInternal) → ()

Pauses execution of this individual task. The task will not fire while paused, regardless of the parent Scope's own pause state.

Calling pause() on an already-paused Handle is a no-op.

Errors

TypeDescription
"Handle is cancelled"Thrown if the Handle is invalid.
"Parent scope is destroyed"Thrown if the parent Scope was destroyed.

resume​

</>
Handle.resume(self: HandleInternal) → ()

Resumes execution of this task after handle:pause(). If the parent Scope is also paused, the task will not fire until the Scope is resumed as well.

Errors

TypeDescription
"Handle is cancelled"Thrown if the Handle is invalid.
"Parent scope is destroyed"Thrown if the parent Scope was destroyed.

setInterval​

</>
Handle.setInterval(
self: HandleInternal,
interval: number--

New interval in seconds.

) → ()

Changes the execution interval for every or tick tasks. The accumulated time resets, so the next execution happens interval seconds from this call.

CAUTION

Only valid for Handles created with scope:every() or scope:tick(). Calling this on an after or frame Handle throws an error.

Errors

TypeDescription
"setInterval is only valid for 'every' and 'tick' handles"Thrown for incompatible handle types.
"Handle is cancelled"Thrown if the Handle is invalid.
"Parent scope is destroyed"Thrown if the parent Scope was destroyed.

isPaused​

</>
Handle.isPaused(self: HandleInternal) → boolean

Returns whether this individual task is paused. Does not account for the parent Scope's pause state — only reflects whether handle:pause() was called.

isCancelled​

</>
Handle.isCancelled(self: HandleInternal) → boolean

Returns whether this task has been cancelled.

Errors

TypeDescription
"Parent scope is destroyed"Thrown if the parent Scope was destroyed.
Show raw api
{
    "functions": [
        {
            "name": "cancel",
            "desc": "Removes this task from the schedule permanently. The Handle becomes invalid\nimmediately and cannot be paused, resumed, or cancelled again.",
            "params": [
                {
                    "name": "self",
                    "desc": "",
                    "lua_type": "HandleInternal"
                }
            ],
            "returns": [],
            "function_type": "static",
            "errors": [
                {
                    "lua_type": "\"Handle is already cancelled\"",
                    "desc": "Thrown if called on an already-cancelled Handle."
                },
                {
                    "lua_type": "\"Parent scope is destroyed\"",
                    "desc": "Thrown if the parent Scope was destroyed."
                }
            ],
            "source": {
                "line": 167,
                "path": "src/Chrono.luau"
            }
        },
        {
            "name": "pause",
            "desc": "Pauses execution of this individual task. The task will not fire while paused,\nregardless of the parent Scope's own pause state.\n\nCalling `pause()` on an already-paused Handle is a no-op.",
            "params": [
                {
                    "name": "self",
                    "desc": "",
                    "lua_type": "HandleInternal"
                }
            ],
            "returns": [],
            "function_type": "static",
            "errors": [
                {
                    "lua_type": "\"Handle is cancelled\"",
                    "desc": "Thrown if the Handle is invalid."
                },
                {
                    "lua_type": "\"Parent scope is destroyed\"",
                    "desc": "Thrown if the parent Scope was destroyed."
                }
            ],
            "source": {
                "line": 189,
                "path": "src/Chrono.luau"
            }
        },
        {
            "name": "resume",
            "desc": "Resumes execution of this task after `handle:pause()`. If the parent Scope is\nalso paused, the task will not fire until the Scope is resumed as well.",
            "params": [
                {
                    "name": "self",
                    "desc": "",
                    "lua_type": "HandleInternal"
                }
            ],
            "returns": [],
            "function_type": "static",
            "errors": [
                {
                    "lua_type": "\"Handle is cancelled\"",
                    "desc": "Thrown if the Handle is invalid."
                },
                {
                    "lua_type": "\"Parent scope is destroyed\"",
                    "desc": "Thrown if the parent Scope was destroyed."
                }
            ],
            "source": {
                "line": 203,
                "path": "src/Chrono.luau"
            }
        },
        {
            "name": "setInterval",
            "desc": "Changes the execution interval for `every` or `tick` tasks. The accumulated\ntime resets, so the next execution happens `interval` seconds from this call.\n\n:::caution\nOnly valid for Handles created with `scope:every()` or `scope:tick()`. Calling\nthis on an `after` or `frame` Handle throws an error.\n:::",
            "params": [
                {
                    "name": "self",
                    "desc": "",
                    "lua_type": "HandleInternal"
                },
                {
                    "name": "interval",
                    "desc": "New interval in seconds.",
                    "lua_type": "number"
                }
            ],
            "returns": [],
            "function_type": "static",
            "errors": [
                {
                    "lua_type": "\"setInterval is only valid for 'every' and 'tick' handles\"",
                    "desc": "Thrown for incompatible handle types."
                },
                {
                    "lua_type": "\"Handle is cancelled\"",
                    "desc": "Thrown if the Handle is invalid."
                },
                {
                    "lua_type": "\"Parent scope is destroyed\"",
                    "desc": "Thrown if the parent Scope was destroyed."
                }
            ],
            "source": {
                "line": 224,
                "path": "src/Chrono.luau"
            }
        },
        {
            "name": "isPaused",
            "desc": "Returns whether this individual task is paused. Does **not** account for the\nparent Scope's pause state — only reflects whether `handle:pause()` was called.",
            "params": [
                {
                    "name": "self",
                    "desc": "",
                    "lua_type": "HandleInternal"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "boolean"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 242,
                "path": "src/Chrono.luau"
            }
        },
        {
            "name": "isCancelled",
            "desc": "Returns whether this task has been cancelled.",
            "params": [
                {
                    "name": "self",
                    "desc": "",
                    "lua_type": "HandleInternal"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "boolean"
                }
            ],
            "function_type": "static",
            "errors": [
                {
                    "lua_type": "\"Parent scope is destroyed\"",
                    "desc": "Thrown if the parent Scope was destroyed."
                }
            ],
            "source": {
                "line": 254,
                "path": "src/Chrono.luau"
            }
        }
    ],
    "properties": [],
    "types": [],
    "name": "Handle",
    "desc": "A reference to a single scheduled task, returned by Scope scheduling methods.\n\nUse a Handle to cancel, pause, resume, or reconfigure a task after scheduling.\nA Handle becomes invalid when `:cancel()` is called or when the parent Scope\nis destroyed. Calling any method on an invalid Handle throws an error.\n\n```lua\nlocal handle = scope:every(5, function()\n\tprint(\"tick\")\nend)\n\nhandle:pause()\nhandle:setInterval(10)\nhandle:resume()\nhandle:cancel()\n```",
    "source": {
        "line": 146,
        "path": "src/Chrono.luau"
    }
}