The trivial-main-thread Reference Manual

This is the trivial-main-thread Reference Manual, version 2.0.0, generated automatically by Declt version 4.0 beta 2 "William Riker" on Sun Dec 15 07:56:33 2024 GMT+0.

Table of Contents


1 Introduction


2 Systems

The main system appears first, followed by any subsystem dependency.


2.1 trivial-main-thread

Compatibility library to run things in the main thread.

Maintainer

Yukari Hafner <>

Author

Yukari Hafner <>

Home Page

https://Shinmera.github.io/trivial-main-thread/

Source Control

(GIT https://github.com/Shinmera/trivial-main-thread.git)

Bug Tracker

https://github.com/Shinmera/trivial-main-thread/issues

License

zlib

Version

2.0.0

Dependencies
  • trivial-features (system).
  • documentation-utils (system).
  • bordeaux-threads (system).
Source

trivial-main-thread.asd.

Child Components

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.


3.1 Lisp


3.1.1 trivial-main-thread/trivial-main-thread.asd

Source

trivial-main-thread.asd.

Parent Component

trivial-main-thread (system).

ASDF Systems

trivial-main-thread.


3.1.2 trivial-main-thread/package.lisp

Source

trivial-main-thread.asd.

Parent Component

trivial-main-thread (system).

Packages

trivial-main-thread.


3.1.3 trivial-main-thread/main-thread.lisp

Dependency

package.lisp (file).

Source

trivial-main-thread.asd.

Parent Component

trivial-main-thread (system).

Public Interface
Internals

3.1.4 trivial-main-thread/documentation.lisp

Dependency

main-thread.lisp (file).

Source

trivial-main-thread.asd.

Parent Component

trivial-main-thread (system).


4 Packages

Packages are listed by definition order.


4.1 trivial-main-thread

Source

package.lisp.

Nicknames
  • org.shirakumo.trivial-main-thread
  • tmt
Use List

common-lisp.

Public Interface
Internals

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


5.1 Public Interface


5.1.1 Special variables

Special Variable: *on-error*

Sets what to do if an error is signalled in the main thread runner.

The value may be one of the following:
:RESIGNAL — Resignal the condition in the calling thread. If the condition is not caused by a task, the debugger is invoked instead
:QUIT — The implementation exits via UIOP:QUIT
NIL
:IGNORE — The error is not handled and the behaviour is implementation-dependent
FUNCTION
SYMBOL — The named function is invoked with the error. Note that this makes the following also permissible: STOP-MAIN-RUNNER
INVOKE-DEBUGGER
CONTINUE
ABORT

Defaults to :RESIGNAL

See START-MAIN-RUNNER
See STOP-MAIN-RUNNER
See CL:INVOKE-DEBUGGER
See CL:CONTINUE
See CL:ABORT
See UIOP:QUIT

Package

trivial-main-thread.

Source

main-thread.lisp.


5.1.2 Macros

Macro: with-body-in-main-thread ((&key blocking) &body body)

Evaluate the BODY in the main thread.

See CALL-IN-MAIN-THREAD

Package

trivial-main-thread.

Source

main-thread.lisp.


5.1.3 Ordinary functions

Function: call-in-main-thread (function &key blocking)

Call FUNCTION in the main thread.

If this is called in the main thread, the function is simply invoked.

Otherwise, ENSURE-MAIN-RUNNER is called and the function is scheduled for execution.

If BLOCKING is non-NIL, the current thread is blocked until the function has finished running and the function’s return values are returned. If the function signals an error and *ON-ERROR* is :RESIGNAL, the error is re-signaled in the calling thread.

See *ON-ERROR*
See MAIN-THREAD-P
See ENSURE-MAIN-RUNNER

Package

trivial-main-thread.

Source

main-thread.lisp.

Function: ensure-main-runner ()

Ensure that the main thread runner is indeed running.

See START-MAIN-RUNNER
See STOP-MAIN-RUNNER

Package

trivial-main-thread.

Source

main-thread.lisp.

Function: main-thread ()

Returns the main thread.

See MAIN-THREAD-P

Package

trivial-main-thread.

Source

main-thread.lisp.

Function: main-thread-p (&optional thread)

Returns true if the given thread is the main thread.

See MAIN-THREAD

Package

trivial-main-thread.

Source

main-thread.lisp.

Function: start-main-runner ()

Starts the runner in the main thread.

If the runner is already running, an error is signalled.

Otherwise, the main thread is hijacked via SWAP-MAIN-THREAD.
The runner keeps a queue of tasks (function thunks) to invoke. When it gets woken up to process tasks (via CALL-IN-MAIN-THREAD), it goes through the queue, invokes the functions in sequence, and puts the function’s return values back into the queue so the caller can process them. If an error is signalled during task processing, the behaviour described in *ON-ERROR* is executed.

See *ON-ERROR*
See SWAP-MAIN-THREAD
See ENSURE-MAIN-RUNNER

Package

trivial-main-thread.

Source

main-thread.lisp.

Function: stop-main-runner (&optional return)

Stops the runner in the main thread, allowing it to continue.

If the runner is not running in the main thread, an error is signalled. If this is called from within the runner, the function causes an unwind.

See START-MAIN-RUNNER

Package

trivial-main-thread.

Source

main-thread.lisp.

Function: swap-main-thread (new-function)

Swaps the main thread for our own FUNCTION.

If the implementation uses the main thread for vital tasks, this function tries to ensure that these vital tasks are continued in a new thread instead.

If this is called from the main thread, the function is simply invoked.

See MAIN-THREAD-P

Package

trivial-main-thread.

Source

main-thread.lisp.


5.2 Internals


5.2.1 Special variables

Special Variable: *main-runner-running-p*
Package

trivial-main-thread.

Source

main-thread.lisp.

Special Variable: *main-thread*
Package

trivial-main-thread.

Source

main-thread.lisp.

Special Variable: *task-cvar*
Package

trivial-main-thread.

Source

main-thread.lisp.

Special Variable: *task-lock*
Package

trivial-main-thread.

Source

main-thread.lisp.

Special Variable: *task-queue*
Package

trivial-main-thread.

Source

main-thread.lisp.


5.2.2 Ordinary functions

Function: find-main-thread ()
Package

trivial-main-thread.

Source

main-thread.lisp.

Function: main-error-handler (e)
Package

trivial-main-thread.

Source

main-thread.lisp.

Function: main-runner ()
Package

trivial-main-thread.

Source

main-thread.lisp.

Function: vector-push-safely (el vector)
Package

trivial-main-thread.

Source

main-thread.lisp.


Appendix A Indexes


A.1 Concepts