Thread

st.thread.Thread(driver, name)
Parameters
  • driver (Driver) – the core driver this thread is running as a part of

  • name (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 queued

  • result_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 queued

  • vararg (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 callback

  • callback (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

table

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 callback

  • callback (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

table

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

table

register_socket(self, socket, callback, name)

Function to register a socket to be watched for read readiness

Parameters
  • self (Thread) – the thread to handle message events

  • socket (socket) – the socket to watch

  • callback (function) – the callback function to call when there is data to read on the socket

  • name (str) – Optional name used for logging

unregister_socket(self, socket)

Function to unregister a socket currently being watched for read readiness

Parameters
  • self (Thread) – the thread on which the socket is currently registered

  • socket (socket) – the socket to stop watching

Returns

the table holding the name and callback of the socket

Return type

table