Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

Utilizzare più thread

Vedi anche

Per un elenco delle primitive multithreading in C++, consultare Multithreading / Concorrenza.

Threads

I thread permettono l'esecuzione simultanea di codice, il che permette di alleggerire il carico del thread principale.

Godot supporta i thread e offre molte funzioni utili per utilizzarli.

Nota

Se si utilizzano altri linguaggi (C#, C++), potrebbe essere più facile usare le classi di threading che tali linguaggi supportano.

Avvertimento

Prima di utilizzare una classe integrata in un thread, consulta prima API thread-safe per verificare se si può utilizzare in modo sicuro in un thread.

Creare un Thread

Per creare un thread, usa il seguente codice:

GDScriptC++ .H FileC++ .CPP File

var thread: Thread

# The thread will start here.
func _ready():
    thread = Thread.new()
    # You can bind multiple arguments to a function Callable.
    thread.start(_thread_function.bind("Wafflecopter"))


# Run here and exit.
# The argument is the bound data passed from start().
func _thread_function(userdata):
    # Print the userdata ("Wafflecopter")
    print("I'm a thread! Userdata is: ", userdata)


# Thread must be disposed (or "joined"), for portability.
func _exit_tree():
    thread.wait_to_finish()

La tua funzione sarà poi eseguita in un thread separato fino al suo ritorno. Anche se la funzione è già ritornata, il thread deve raccoglierla, quindi chiama Thread.wait_to_finish(), il quale attenderà che il thread abbia terminato (se non ha ancora terminato), e poi la rilascerà correttamente.

Avvertimento

La creazione di thread è un'operazione lenta, soprattutto su Windows. Per evitare un inutile sovraccarico sulle prestazioni, assicurati di creare i thread prima che sia necessaria un'elaborazione intensa, anziché crearli all'ultimo momento.

Ad esempio, se hai bisogno di più thread durante il gioco, puoi crearli mentre il livello si sta caricando e iniziare a elaborarli solo in un secondo momento.

Inoltre, il blocco e lo sblocco dei mutex possono essere operazioni costose. Bloccare richiede attenzione; evita di bloccare troppo spesso (o per troppo tempo).

Mutex

Accedere a oggetti o dati da più thread non è sempre supportato (se lo si fa, potrebbero accadere comportamenti imprevisti o arresti anomali). Consulta la documentazione API thread-safe per conoscere quali API del motore supportano l'accesso da più thread.

Quando si elaborano i propri dati o si chiamano le proprie funzioni, come regola generale, è consigliabile evitare di accedere direttamente agli stessi dati da thread diversi. Potrebbero esserci problemi di sincronizzazione, poiché i dati non vengono sempre aggiornati tra i core della CPU quando vengono modificati. Utilizzare sempre un Mutex quando si accede a un dato da thread diversi.

Quando si chiama Mutex.lock(), un thread garantisce che tutti gli altri thread vengano bloccati (messi in stato di sospensione) se tentano di bloccare lo stesso mutex. Quando il mutex viene sbloccato chiamando Mutex.unlock(), agli altri thread sarà permesso di procedere con il blocco (ma solo uno alla volta).

Ecco un esempio di utilizzo di un Mutex:

GDScriptC++ .H FileC++ .CPP File

var counter := 0
var mutex: Mutex
var thread: Thread


# The thread will start here.
func _ready():
    mutex = Mutex.new()
    thread = Thread.new()
    thread.start(_thread_function)

    # Increase value, protect it with Mutex.
    mutex.lock()
    counter += 1
    mutex.unlock()


# Increment the value from the thread, too.
func _thread_function():
    mutex.lock()
    counter += 1
    mutex.unlock()


# Thread must be disposed (or "joined"), for portability.
func _exit_tree():
    thread.wait_to_finish()
    print("Counter is: ", counter) # Should be 2.

Semafori

A volte si desidera che un thread funzioni "su richiesta". In altre parole, indicargli quando lavorare e lasciarlo in sospeso quando non sta facendo nulla. A questo scopo si utilizzano i Semaphore. La funzione Semaphore.wait() serve dentro il thread per sospenderlo fino all'arrivo di qualsiasi dato.

Il thread principale, invece, usa Semaphore.post() per segnalare che i dati sono pronti per essere elaborati:

GDScriptC++ .H FileC++ .CPP File

var counter := 0
var mutex: Mutex
var semaphore: Semaphore
var thread: Thread
var exit_thread := false


# The thread will start here.
func _ready():
    mutex = Mutex.new()
    semaphore = Semaphore.new()
    exit_thread = false

    thread = Thread.new()
    thread.start(_thread_function)


func _thread_function():
    while true:
        semaphore.wait() # Wait until posted.

        mutex.lock()
        var should_exit = exit_thread # Protect with Mutex.
        mutex.unlock()

        if should_exit:
            break

        mutex.lock()
        counter += 1 # Increment counter, protect with Mutex.
        mutex.unlock()


func increment_counter():
    semaphore.post() # Make the thread process.


func get_counter():
    mutex.lock()
    # Copy counter, protect with Mutex.
    var counter_value = counter
    mutex.unlock()
    return counter_value


# Thread must be disposed (or "joined"), for portability.
func _exit_tree():
    # Set exit condition to true.
    mutex.lock()
    exit_thread = true # Protect with Mutex.
    mutex.unlock()

    # Unblock by posting.
    semaphore.post()

    # Wait until it exits.
    thread.wait_to_finish()

    # Print the counter.
    print("Counter is: ", counter)