Thread
- st.thread.Thread(driver, name)
- Parameters
driver (
Driver) – the core driver this thread is running as a part ofname (
str) – the name of this thread
- class st.thread.Thread
A handle to a cooperatively scheduled thread that processes events sequentially.
A thread object provides an abstraction over the cosock coroutine executor allowing for two or more functions to execute in a controlled manner. It also provides utility functions for creating timers (oneshot and periodic) that run on the provided thread.
- queue_event_with_handler(callback, result_handler, ...)
Queues an event to run on the thread
Queues an event in the form of a function and zero or more parameters to pass to that function. The event will be run once any previously queued events have finished running. Also provides a result_handler function for processing the results of the callback invocation in the following way:
The provided event function will be executed in a pcall context. The handler will be run on the results of the pcall, so it should expect two arguments: the pcall status, and the rest of the pcall return; this means that the 2nd argument to the handler function will be either the error or a packed table with the return values from the event function.
- Parameters
callback (
function) – The function to be queuedresult_handler (
function) – The handler function. This function should take two arguments, the pcall return code and the pcall return values (either the error or the first callback’s returns)vararg (
any) – Zero or more parameters to be passed to the callback function when it is called
- queue_event(callback, ...)
Queues an event to run on the thread
Queues an event in the form of a function and zero or more parameters to pass to that function. The event will be run once any previously queued events have finished running.
- Parameters
callback (
function) – The function to be queuedvararg (
any) – Zero or more parameters to be passed to the callback function when it is called
- close()
Closes the thread to new events
Closes the thread to new events, including expiring timers, but does not clear events that have already been queued. After all already queued events have been processed the thread exits.
- call_with_delay(delay_s, callback, name)
Creates a oneshot timer on this thread
Usage:
thread:call_with_delay(5.0, my_timer_callback)- Parameters
delay_s (
number) – The number of seconds to wait before hitting the callbackcallback (
function) – The function to call when the timer expires.name (
str) – an optional name for the timer
- Returns
The created timer if successful, otherwise nil
- Return type
- call_on_schedule(interval_s, callback, name)
Creates a periodic timer on this thread
Usage:
thread:call_on_schedule(5.0, my_timer_callback)- Parameters
interval_s (
number) – The number of seconds to wait between hitting the callbackcallback (
function) – The function to call when the timer expires.name (
str) – an optional name for the timer
- Returns
The created timer if successful, otherwise nil
- Return type
- cancel_timer(timer)
Cancel a timer set up on this thread
Usage:
thread:cancel_timer(my_timer)- Parameters
timer (
Timer) – The timer to cancel- Returns
the table holding the name and callback of the timer
- Return type
- register_socket(self, socket, callback, name)
Function to register a socket to be watched for read readiness
- unregister_socket(self, socket)
Function to unregister a socket currently being watched for read readiness