Repository files navigation

Warning

This branch is only usable with Godot 4.For Godot 3 support, check out thegodot-3 branch.

Threaded or synchronous Dispatch Queues forGodot.

Threaded Dispatch Queues are also known as Thread Pools.

Available at the Asset Library asDispatch Queue.

# 1) Instantiatevardispatch_queue=DispatchQueue.new()# 2.a) Either create a serial...dispatch_queue.create_serial()# 2.b) ...or concurrent queuedispatch_queue.create_concurrent(OS.get_processor_count())# (if you do neither, DispatchQueue will run in synchronous mode)# 3) Dispatch methods, optionally responding to tasks and task groups "finished" signal# 3.a) Fire and forget styledispatch_queue.dispatch(self.method_name.bind("optional","method","arguments")).then(self.result_callback)dispatch_queue.dispatch_group([self.method_name1.bind("optional","arguments"),self.method_name2,self.method_name3,]).then_deferred(self.group_results_callback)# 3.b) Coroutine stylevartask=dispatch_queue.dispatch(self.mymethod)varmymethod_result=awaittask.finishedvartask_group=dispatch_queue.dispatch_group([self.method1,self.method2])vargroup_method_results=awaittask_group.finished# 4) Optionally respond to the `all_tasks_finished` signal to know when all tasks have finished# 4.a) Connect styledispatch_queue.all_tasks_finished.connect(self._on_all_tasks_finished)# 4.b) Coroutine styleawaitdispatch_queue.all_tasks_finished# DispatchQueue extends RefCounted, so no need to worry about freeing it manually

There is a Node script (addons/dispatch_queue/dispatch_queue_node.gd)that wraps every aspect of dispatch queues. Useful for having a local queue in a scene or as an Autoload.

There is also a Resource script (addons/dispatch_queue/dispatch_queue_resource.gd)that wraps every aspect of dispatch queues. Useful for sharing queues with multiple objects between scenes without resorting to Autoload.

signal all_tasks_finished()

• Emitted when the last queued Task finishes.This signal is emitted deferred, so it is safe to call nonThread-safe APIs.

create_serial()

• Creates a Thread of execution to process tasks.If threading is not supported, fallback to synchronous mode.If queue was already serial, this is a no-op, otherwisecallsshutdown and create a new Thread.

create_concurrent(thread_count: int = 1)

• Createsthread_count Threads of execution to process tasks.If threading is not supported, fallback to synchronous mode.If queue was already concurrent withthread_count Threads,this is a no-op, otherwise callsshutdown and create new Threads.Ifthread_count <= 1, creates a serial queue.

dispatch(callable: Callable, priority: int = 0) -> Task

• Create a Task for executingcallable, optionally setting apriorityOn threaded mode, the Task will be queued to be executed on a Thread inpriority order.On synchronous mode, the Task will be queued to be executed inpriority order on the next frame.Tasks whosepriority is lower will execute first.

dispatch_group(task_list: Array[Callable], priority: int = 0) -> TaskGroup

• Create all tasks intask_list by callingdispatch on each value with prioritypriority, returning the TaskGroup associated with them.TaskGroups whosepriority is lower will execute first.

is_threaded() -> bool

• Returns whether queue is threaded or synchronous.

get_thread_count() -> int

• Returns the current Thread count.Returns 0 on synchronous mode.

size() -> int

• Returns the number of queued tasks.

is_empty() -> bool

• Returns whether queue is empty, that is, there are no tasks queued.

clear()

• Cancel pending Tasks, clearing the current queue.Tasks that are being processed will still run to completion.

shutdown()

• Cancel pending Tasks, wait and release the used Threads.The queue now runs in synchronous mode, so that new tasks will run in the main thread.Callcreate_serial orcreate_concurrent to recreate the worker threads.This method is called automatically onNOTIFICATION_PREDELETE.It is safe to call this more than once.

signal finished(result)

• Emitted after Task executes, passing the result as argument.The signal is emitted in the same Thread that executed the Task, so youneed to connect withCONNECT_DEFERRED if you want to call nonThread-safeAPIs.

then(callable: Callable, flags: int = 0)

• Helper method for connecting to the "finished" signal.This enables the following pattern:

  dispatch_queue.dispatch(task).then(continuation_callable)

then_deferred(callable: Callable, flags: int = 0)

• Alias forthen that also addsCONNECT_DEFERRED to flags.

  dispatch_queue.dispatch(task).then_deferred(continuation_callable)

signal finished(results)

• Emitted after all Tasks in the group finish, passing the results Array as argument.The signal is emitted in the same Thread that executed the last pending Task, so youneed to connect withCONNECT_DEFERRED if you want to call nonThread-safeAPIs.

then(callable: Callable, flags: int = 0)

• Helper method for connecting to the "finished" signal.This enables the following pattern:

  dispatch_queue.dispatch_group(task_list).then(continuation_callable)

then_deferred(callable: Callable, flags: int = 0)

• Alias forthen that also addsCONNECT_DEFERRED to flags.

  dispatch_queue.dispatch_group(task_list).then_deferred(continuation_callable)

Node that wraps a DispatchQueue.

Apart from creation, all DispatchQueue public methods and signals are supported.

Creates the Threads when entering tree and shuts down when exiting tree.

export(int) var thread_count = -1

• Number of Threads DispatchQueue will utilize.Ifthread_count == 0, runs queue in synchronous mode.Ifthread_count < 0, createsOS.get_processor_count() Threads.

Resource that wraps a DispatchQueue.

Apart from creation, all DispatchQueue public methods and signals are supported.

export(int) var thread_count = -1

• Number of Threads DispatchQueue will utilize.Ifthread_count == 0, runs queue in synchronous mode.Ifthread_count < 0, createsOS.get_processor_count() Threads.

• Conveyor icon bysmalllikeart:https://www.flaticon.com/free-icon/conveyor_888545

• GODOThreadPOOL:https://github.com/zmarcos/godothreadpool