rojo/.cursor/rules/roblox/reference/engine/libraries/task.yaml

# This file is automatically generated. Please don't edit it manually.
# To submit a bug report on the content, see
# https://devforum.roblox.com/c/bug-reports/documentation-issues/72

name: task
type: library
summary: |
  Allows for functions and threads to be coordinated with the engine's
  scheduler.
description: |
  The **task** library allows for functions and threads to be scheduled with the
  engine's scheduler.

  The functions available in this library generally support functions and
  threads. In most cases using a function is sufficient, but for more advanced
  cases it's recommended you familiarize yourself with the `Library.coroutine`
  library.
tags: []
code_samples: []
properties: []
functions:
  - name: task.spawn
    summary: |
      Calls/resumes a function/coroutine immediately through the engine's
      scheduler.
    description: |
      Accepts a function or a thread (as returned by
      `Library.coroutine.create()`) and calls/resumes it immediately through the
      engine's scheduler. Arguments after the first are sent to the
      function/thread.

      If the calling script is currently running in a serial execution phase,
      then the spawned function or thread is resumed in the current serial
      execution phase. If the calling script is currently running in a parallel
      execution phase, then the spawned function or thread is resumed in the
      current parallel execution phase. For more information, see
      [Parallel Luau](../../../scripting/multithreading.md).
    parameters:
      - name: functionOrThread
        type: function | thread
        default:
        summary: |
          A function or a thread returned by `Library.coroutine.create()`.
      - name: ...
        type: Variant
        default:
        summary: |
          Arguments to send to the function or thread.
    returns:
      - type: thread
        summary: |
          The scheduled thread.
    tags: []
    code_samples: []
    deprecation_message: ''
  - name: task.defer
    summary: |
      Calls/resumes a function/coroutine at the end of the current resumption
      cycle.
    description: |
      Accepts a function or a thread (as returned by
      `Library.coroutine.create()`) and defers it until the end of the current
      resume point within the current frame.

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

      If the calling script is currently running in a serial execution phase,
      then the deferred function or thread is resumed in a serial execution
      phase. If the calling script is currently running in a parallel execution
      phase, then the deferred function or thread is resumed in a parallel
      execution phase. For more information, see
      [Parallel Luau](../../../scripting/multithreading.md).
    parameters:
      - name: functionOrThread
        type: function | thread
        default:
        summary: |
          A function or a thread returned by coroutine.create.
      - name: ...
        type: Variant
        default:
        summary: |
          Arguments to send to the function or thread.
    returns:
      - type: thread
        summary: |
          The scheduled thread.
    tags: []
    code_samples: []
    deprecation_message: ''
  - name: task.delay
    summary: |
      Schedules a function/coroutine to be called/resumed on the next Heartbeat
      after the given duration (in seconds) has passed, without throttling.
    description: |
      Accepts a function or a thread (as returned by
      `Library.coroutine.create()`) and schedules it to be called/resumed on the
      next `Class.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 deprecated global `delay()` function in
      that **no throttling occurs**: on the very same
      `Class.RunService.Heartbeat|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 `Class.RunService.Heartbeat|Heartbeat`.

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

      If the calling script is currently running in a serial execution phase,
      then the delayed function or thread is resumed in a serial execution
      phase. If the calling script is currently running in a parallel execution
      phase, then the delayed function or thread is resumed in a parallel
      execution phase. For more information, see
      [Parallel Luau](../../../scripting/multithreading.md).
    parameters:
      - name: duration
        type: number
        default:
        summary: |
          The minimum number of seconds that must pass before the
          function/thread is called/resumed.
      - name: functionOrThread
        type: function | thread
        default:
        summary: ''
      - name: ...
        type: Variant
        default:
        summary: |
          Arguments to be passed to the function/thread when it is due to be
          called/resumed.
    returns:
      - type: thread
        summary: |
          The scheduled thread.
    tags: []
    code_samples: []
    deprecation_message: ''
  - name: task.desynchronize
    summary: |
      Causes the following code to be run in parallel.
    description: |
      If the calling script is currently running in a serial execution phase,
      `desynchronize()` suspends the script and the script will be resumed in
      the next parallel execution phase. If the calling script is currently
      running in a parallel execution phase, `desynchronize()` returns
      immediately and has no effect.

      Only scripts which are descendants of an `Class.Actor` may call this
      method. If a script outside of an `Class.Actor` calls this method, an
      error will be raised. `Class.ModuleScript|ModuleScripts` may also call
      `desynchronize()` as long as the instantiation of the module calling it
      was required by a script that is a descendant of an `Class.Actor`.

      For more information, see
      [Parallel Luau](../../../scripting/multithreading.md).
    parameters: []
    returns:
      - type: ()
        summary: ''
    tags: []
    code_samples: []
    deprecation_message: ''
  - name: task.synchronize
    summary: |
      Causes the following code to be run in serial.
    description: |
      If the calling script is currently running in a parallel execution phase,
      `synchronize()` suspends the script and the script will be resumed in the
      next serial execution phase. If the calling script is currently running in
      a serial execution phase, `synchronize()` returns immediately and has no
      effect.

      Only scripts which are descendants of an `Class.Actor` may call this
      method. If a script outside of an `Class.Actor` calls this method, an
      error will be raised. `Class.ModuleScript|ModuleScripts` may also call
      `synchronize()` as long as the instantiation of the module calling it was
      required by a script that is a descendant of an `Class.Actor`.

      For more information, see
      [Parallel Luau](../../../scripting/multithreading.md).
    parameters: []
    returns:
      - type: ()
        summary: ''
    tags: []
    code_samples: []
    deprecation_message: ''
  - name: task.wait
    summary: |
      Yields the current thread without throttling.
    description: |
      Yields the current thread until the given duration (in seconds) has
      elapsed, then resumes the thread on the next
      `Class.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
      `Class.RunService.Heartbeat:Wait()`

      Unlike the deprecated 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.

      If the calling script is currently running in a serial execution phase,
      then the script is resumed in a serial execution phase. If the calling
      script is currently running in a parallel execution phase, then the script
      is resumed in a parallel execution phase. For more information, see
      [Parallel Luau](../../../scripting/multithreading.md).
    parameters:
      - name: duration
        type: number
        default: 0
        summary: |
          The amount of time in seconds that should elapse before the current
          thread is resumed.
    returns:
      - type: number
        summary: ''
    tags: []
    code_samples: []
    deprecation_message: ''
  - name: task.cancel
    summary: |
      Cancels a thread, preventing it from being resumed.
    description: |
      Cancels a thread and closes it, preventing it from being resumed manually
      or by the engine's scheduler.

      This function can be used with other members of the **task** library that
      return a thread to cancel them before they are resumed. For example:

      ```lua
      local thread = task.delay(5, function()
      	print("Hello world!")
      end)

      task.cancel(thread)
      ```

      Note that threads may be in a state where it is impossible to cancel them.
      For example, the currently executing thread and threads that have resumed
      another coroutine may not be cancelled. If this is the case, an error will
      be generated. However, code should not rely on specific thread states or
      conditions causing `Library.task.cancel()` to fail. It is possible that
      future updates will eliminate these constraints and allow threads in these
      states to be successfully cancelled.
    parameters:
      - name: thread
        type: thread
        default:
        summary: |
          The thread that will be cancelled.
    returns:
      - type: ()
        summary: ''
    tags: []
    code_samples: []
    deprecation_message: ''