Thread

Documentation

Overview

A unit of execution in a process. Can run methods on Objects simultaneously. The use of synchronization via Mutex or Semaphore is advised if working with shared objects.

Warning:

To ensure proper cleanup without crashes or deadlocks, when a Thread's reference count reaches zero and it is therefore destroyed, the following conditions must be met:

- It must not have any Mutex objects locked.

- It must not be waiting on any Semaphore objects.

- WaitToFinish should have been called on it.

Index

• func SetThreadSafetyChecksEnabled(enabled bool)
• type Advanced
• type Any
• type Expanded
• type Extension
  • func (self *Extension[T]) AsObject() [1]gd.Object
  • func (self *Extension[T]) AsRefCounted() [1]gd.RefCounted
  • func (self *Extension[T]) AsThread() Instance
• type ID
  • func (id ID) Instance() (Instance, bool)
• type Instance
  • func New() Instance
  • func (self Instance) AsObject() [1]gd.Object
  • func (self Instance) AsRefCounted() [1]gd.RefCounted
  • func (self Instance) AsThread() Instance
  • func (self Instance) GetId() string
  • func (self Instance) ID() ID
  • func (self Instance) IsAlive() bool
  • func (self Instance) IsStarted() bool
  • func (self Instance) MoreArgs() MoreArgs
  • func (self *Instance) SetObject(obj [1]gd.Object) bool
  • func (self Instance) Start(callable func()) error
  • func (self Instance) Virtual(name string) reflect.Value
  • func (self Instance) WaitToFinish() any
• type MoreArgs
  • func (self MoreArgs) Start(callable func(), priority Priority) error
• type Priority

Functions

func SetThreadSafetyChecksEnabled

func SetThreadSafetyChecksEnabled(enabled bool)

Sets whether the thread safety checks the engine normally performs in methods of certain classes (e.g., Node) should happen on the current thread.

The default, for every thread, is that they are enabled (as if called with 'enabled' being true).

Those checks are conservative. That means that they will only succeed in considering a call thread-safe (and therefore allow it to happen) if the engine can guarantee such safety.

Because of that, there may be cases where the user may want to disable them ('enabled' being false) to make certain operations allowed again. By doing so, it becomes the user's responsibility to ensure thread safety (e.g., by using Mutex) for those objects that are otherwise protected by the engine.

Note: This is an advanced usage of the engine. You are advised to use it only if you know what you are doing and there is no safer way.

Note: This is useful for scripts running on either arbitrary Thread objects or tasks submitted to the WorkerThreadPool. It doesn't apply to code running during Node group processing, where the checks will be always performed.

Note: Even in the case of having disabled the checks in a WorkerThreadPool task, there's no need to re-enable them at the end. The engine will do so.

Types

type Advanced

type Advanced = class

Advanced exposes a 1:1 low-level instance of the class, undocumented, for those who know what they are doing.

type Any

type Any interface {
	gd.IsClass
	AsThread() Instance
}

type Expanded

type Expanded = MoreArgs

type Extension

type Extension[T gdclass.Interface] struct{ gdclass.Extension[T, Instance] }

Extension can be embedded in a new struct to create an extension of this class. T should be the type that is embedding this Extension

func (*Extension[T]) AsObject

func (self *Extension[T]) AsObject() [1]gd.Object

func (*Extension[T]) AsRefCounted

func (self *Extension[T]) AsRefCounted() [1]gd.RefCounted

func (*Extension[T]) AsThread

func (self *Extension[T]) AsThread() Instance

type ID

type ID Object.ID

ID is a typed object ID (reference) to an instance of this class, use it to store references to objects with unknown lifetimes, as an ID will not panic on use if the underlying object has been destroyed.

func (ID) Instance

func (id ID) Instance() (Instance, bool)

type Instance

type Instance [1]gdclass.Thread

Instance of the class with convieniently typed arguments and results.

var Nil Instance

Nil is a nil/null instance of the class. Equivalent to the zero value.

func New

func New() Instance

func (Instance) AsObject

func (self Instance) AsObject() [1]gd.Object

func (Instance) AsRefCounted

func (self Instance) AsRefCounted() [1]gd.RefCounted

func (Instance) AsThread

func (self Instance) AsThread() Instance

func (Instance) GetId

func (self Instance) GetId() string

Returns the current Thread's ID, uniquely identifying it among all threads. If the Thread has not started running or if WaitToFinish has been called, this returns an empty string.

func (Instance) ID

func (self Instance) ID() ID

func (Instance) IsAlive

func (self Instance) IsAlive() bool

Returns true if this Thread is currently running the provided function. This is useful for determining if WaitToFinish can be called without blocking the calling thread.

To check if a Thread is joinable, use IsStarted.

func (Instance) IsStarted

func (self Instance) IsStarted() bool

Returns true if this Thread has been started. Once started, this will return true until it is joined using WaitToFinish. For checking if a Thread is still executing its task, use IsAlive.

func (Instance) MoreArgs

func (self Instance) MoreArgs() MoreArgs

MoreArgs enables certain functions to be called with additional 'optional' arguments.

func (*Instance) SetObject

func (self *Instance) SetObject(obj [1]gd.Object) bool

func (Instance) Start

func (self Instance) Start(callable func()) error

Starts a new Thread that calls 'callable'.

If the method takes some arguments, you can pass them using Callable.Bind.

The 'priority' of the Thread can be changed by passing a value from the Priority enum.

Returns [Ok] on success, or [ErrCantCreate] on failure.

func (Instance) Virtual

func (self Instance) Virtual(name string) reflect.Value

func (Instance) WaitToFinish

func (self Instance) WaitToFinish() any

Joins the Thread and waits for it to finish. Returns the output of the func passed to Start.

Should either be used when you want to retrieve the value returned from the method called by the Thread or before freeing the instance that contains the Thread.

To determine if this can be called without blocking the calling thread, check if IsAlive is false.

type MoreArgs

type MoreArgs [1]gdclass.Thread

MoreArgs is a container for Instance functions with additional 'optional' arguments.

func (MoreArgs) Start

func (self MoreArgs) Start(callable func(), priority Priority) error

Starts a new Thread that calls 'callable'.

If the method takes some arguments, you can pass them using Callable.Bind.

The 'priority' of the Thread can be changed by passing a value from the Priority enum.

Returns [Ok] on success, or [ErrCantCreate] on failure.

type Priority

type Priority int //gd:Thread.Priority

const (
	// A thread running with lower priority than normally.
	PriorityLow Priority = 0
	// A thread with a standard priority.
	PriorityNormal Priority = 1
	// A thread running with higher priority than normally.
	PriorityHigh Priority = 2
)