Home
Ratchet Library :: API Reference
API  ·  Manual

Module ratchet.thread

This module provides as set of functions for creating and controlling threads from within the context of a running ratchet. These functions do not need to be passed a ratchet object, they will deduce it from the current thread.

Functions

alarm (seconds, callback) Adds a background timer to the current thread.
attach (func, ...) Queues a new thread for execution.
attach_background (func, ...) Queues a new thread for execution.
block_on (reads, writes, timeout) Blocks on multiple items, with a single timeout.
kill (thread) Kills a given thread.
kill_all (threads) Kills all threads in the table sequence.
pause () Pauses the current thread indefinitely.
self () Returns the Lua thread object that is currently running, or nil for the main thread.
sigwait (signal) Blocks the current thread until the current process receives the given signal.
space (premade) Returns a table that is specific to the currently-running thread that can be used as scratch-space for thread-scope data.
timer (seconds) Pauses the current thread for the given period.
unpause (thread, ...) Unpauses the given thread.
wait_all (threads) Pauses the current thread until all threads listed in the given table have completed their execution either normally or by error.


Functions

alarm (seconds, callback)
Adds a background timer to the current thread. If the thread outruns the timer, the callback is run and a ratchet error of type "ALARM" is thrown.

Parameters

  • seconds: trigger the alarm after this many seconds elapse.
  • callback: optional callback function to run before throwing error.
attach (func, ...)
Queues a new thread for execution. The thread calls func and gives it any extra arguments as its parameters. The thread is not started by this method, instead it is started on next iteration of the loop. All threads attached with this method must be completed before loop() will finish.

Parameters

  • func: the function to run in the thread.
  • ...: extra parameters to function.

Return value:

a Lua thread object.
attach_background (func, ...)
Queues a new thread for execution. The thread calls func and gives it any extra arguments as its parameters. The thread is not started by this method, instead it is started on next iteration of the loop. Threads attached with this method as opposed to attach() will be destroyed when loop() finishes, whether completed or not.

Parameters

  • func: the function to run in the thread.
  • ...: extra parameters to function.

Return value:

a Lua thread object.
block_on (reads, writes, timeout)
Blocks on multiple items, with a single timeout. This function will block until the first event on any one of the items. Items given in the read and write argument tables must have a get_fd() method that returns its file descriptor.

Parameters

  • reads: Table of items to wait for read events on.
  • writes: Table of items to wait for write events on.
  • timeout: Returns nil if this many seconds elapse with no events.

Return value:

The item from the read or write table that triggered an event.
kill (thread)
Kills a given thread. If the thread is yielding on any events, those events are cleaned up and the thread is dropped.

Parameters

  • thread: The thread to kill.
kill_all (threads)
Kills all threads in the table sequence. Essentially this function is the same as kill() but run in a loop over a table.

Parameters

  • threads: table array of threads to kill.
pause ()
Pauses the current thread indefinitely. The thread must be resumed by a call to unpause() from another thread.

Return value:

any extra arguments passed to unpause() from other thread.
self ()
Returns the Lua thread object that is currently running, or nil for the main thread.

Return value:

thread object or nil.
sigwait (signal)
Blocks the current thread until the current process receives the given signal.

Parameters

  • signal: A signal by number or name (see signal(7)).
space (premade)
Returns a table that is specific to the currently-running thread that can be used as scratch-space for thread-scope data. This table is not created until the first time this method is called for in thread.

Parameters

  • premade: optionally pass in a pre-existing object to be stored as the thread's scratch space instead of the default a new table.

Return value:

a table specific to the current thread.
timer (seconds)
Pauses the current thread for the given period.

Parameters

  • seconds: resume thread after this many seconds elapse.
unpause (thread, ...)
Unpauses the given thread. The paused thread will resume on next iteration of the main loop. Extra parameters to this function will be given to the paused thread as return values from pause().

Parameters

  • thread: the thread to unpause.
  • ...: extra parameters will be returned by pause().
wait_all (threads)
Pauses the current thread until all threads listed in the given table have completed their execution either normally or by error.

Parameters

  • threads: table containing threads to wait for.