The trivial-main-thread Reference Manual

Table of Contents

Next: , Previous: , Up: (dir)   [Contents][Index]

The trivial-main-thread Reference Manual

This is the trivial-main-thread Reference Manual, version 1.0.0, generated automatically by Declt version 2.3 "Robert April" on Tue Jan 09 15:55:23 2018 GMT+0.


Next: , Previous: , Up: Top   [Contents][Index]

1 Introduction

About trivial-main-thread

Sometimes it is absolutely necessary to run certain tasks in the main thread of the implementation. This is particularly the case with GUI applications on OS X, where only thread 0 is allowed to issue drawing calls. This library aims to help with that.

Why a Wrapper

Why not just call bt:interrupt-thread and be done with it? Well, an implementation is not required to provide the user with the main thread, and may instead choose to use it for its own purposes. For example, CCL uses the thread for housekeeping and signal handling. As such, some implementations require workarounds to make this go by smoothly. That's why this library exists.

Basic Usage

Load trivial-main-thread through ASDF or Quicklisp.

(ql:quickload :trivial-main-thread)

Now you can simply issue calls to be sent to the main thread by using call-in-main-thread or with-body-in-main-thread.

(call-in-main-thread (lambda () (+ 1 1)))
(with-body-in-main-thread (:blocking T)
  (+ 1 1))

Upon first usage of either of these two functions, trivial-main-thread will start a new thread to resume the main thread's functionality in if necessary, and interrupt the main thread with a task runner loop. From then on, call requests can be sent to the thread. For more information on the tasks and runners system, see simple-tasks.

For example, if you wanted to start a Qt application, you could do the following:

(call-in-main-thread #'qt:make-qapplication)
(with-body-in-main-thread ()
  (qt:with-main-window (window (make-instance 'my-window))))

And the application will safely run in the main thread.

In the case where the main thread /is/ the evaluating thread, no additional threads are started, and the runner used will simply directly run tasks.

Supported Implementations

The following are explicitly unsupported:

Also See


Next: , Previous: , Up: Top   [Contents][Index]

2 Systems

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


Previous: , Up: Systems   [Contents][Index]

2.1 trivial-main-thread

Maintainer

Nicolas Hafner <shinmera@tymoon.eu>

Author

Nicolas Hafner <shinmera@tymoon.eu>

Home Page

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

License

Artistic

Description

Compatibility library to run things in the main thread.

Version

1.0.0

Dependencies
Source

trivial-main-thread.asd (file)

Components

Next: , Previous: , Up: Top   [Contents][Index]

3 Files

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


Previous: , Up: Files   [Contents][Index]

3.1 Lisp


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.1 trivial-main-thread.asd

Location

trivial-main-thread.asd

Systems

trivial-main-thread (system)


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.2 trivial-main-thread/package.lisp

Parent

trivial-main-thread (system)

Location

package.lisp

Packages

trivial-main-thread


Next: , Previous: , Up: Lisp files   [Contents][Index]

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

Dependency

package.lisp (file)

Parent

trivial-main-thread (system)

Location

main-thread.lisp

Exported Definitions
Internal Definitions

Previous: , Up: Lisp files   [Contents][Index]

3.1.4 trivial-main-thread/documentation.lisp

Dependency

main-thread.lisp (file)

Parent

trivial-main-thread (system)

Location

documentation.lisp

Internal Definitions

setdocs (macro)


Next: , Previous: , Up: Top   [Contents][Index]

4 Packages

Packages are listed by definition order.


Previous: , Up: Packages   [Contents][Index]

4.1 trivial-main-thread

Source

package.lisp (file)

Nicknames
Use List

common-lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

5 Definitions

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


Next: , Previous: , Up: Definitions   [Contents][Index]

5.1 Exported definitions


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.1 Special variables

Special Variable: *main-thread*

Holds the main thread.

Package

trivial-main-thread

Source

main-thread.lisp (file)

Special Variable: *runner*

Holds the runner object to be set into the main thread.

See SIMPLE-TASKS:RUNNER

Package

trivial-main-thread

Source

main-thread.lisp (file)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.2 Macros

Macro: with-body-in-main-thread (&key BLOCKING RUNNER) &body BODY

Evaluate the BODY in the main thread. This always calls ENSURE-MAIN-RUNNER-STARTED.

See CALL-IN-MAIN-THREAD

Package

trivial-main-thread

Source

main-thread.lisp (file)


Previous: , Up: Exported definitions   [Contents][Index]

5.1.3 Functions

Function: call-in-main-thread FUNCTION &key BLOCKING RUNNER

Call FUNCTION in the main thread.
This always calls ENSURE-MAIN-RUNNER-STARTED.

If BLOCKING is non-NIL, the current thread is blocked until the function has finished running. The function’s return values are returned. Otherwise, the task created to call the function is returned.

See SIMPLE-TASKS:CALL-AS-TASK

Package

trivial-main-thread

Source

main-thread.lisp (file)

Function: ensure-main-runner &key MAIN-THREAD RUNNER

Ensure that the main thread runner is indeed running.

If the MAIN-THREAD is EQL to BT:CURRENT-THREAD, then the RUNNER is CHANGE-CLASSed into SIMPLE-TASK:RUNNER. This runner class does not use threading and instead directly executes the tasks. If we did not do this, situations where the main thread is the currently evaluating thread, we would block it forever, and thus stop it from ever reaching any task scheduling calls.

Package

trivial-main-thread

Source

main-thread.lisp (file)

Function: ensure-main-runner-started &key MAIN-THREAD RUNNER

Ensure that the main thread runner is indeed started.
This calls ENSURE-MAIN-RUNNER and then sleeps until the runner reports itself as running.

Package

trivial-main-thread

Source

main-thread.lisp (file)

Function: find-main-thread ()

Attempts to find the main thread (thread 0) of the implementation.

If no implementation specific handling is implemented, the last thread in the list of threads reported by BT:ALL-THREADS is primitively chosen.

Package

trivial-main-thread

Source

main-thread.lisp (file)

Function: schedule-task TASK &optional RUNNER

Schedule TASK to be run on the main thread runner. This always calls ENSURE-MAIN-RUNNER-STARTED.

See SIMPLE-TASKS:SCHEDULE-TASK

Package

trivial-main-thread

Source

main-thread.lisp (file)

Function: start-main-runner &key MAIN-THREAD RUNNER

Starts the runner in the main thread.

If a runner or main-thread is passed explicitly, *RUNNER* and *MAIN-THREAD* are set to those values respectively.

See SIMPLE-TASKS:START-RUNNER
See SWAP-MAIN-THREAD

Package

trivial-main-thread

Source

main-thread.lisp (file)

Function: stop-main-runner &key MAIN-THREAD RUNNER

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

This will destroy any sidestepping thread that might have been created by SWAP-THREAD.

Package

trivial-main-thread

Source

main-thread.lisp (file)

Function: swap-main-thread NEW-FUNCTION &optional MAIN-THREAD

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 the MAIN-THREAD is EQL to BT:CURRENT-THREAD, then the FUNCTION is simply called.

Package

trivial-main-thread

Source

main-thread.lisp (file)


Previous: , Up: Definitions   [Contents][Index]

5.2 Internal definitions


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.1 Macros

Macro: %ensure-mt VAR
Package

trivial-main-thread

Source

main-thread.lisp (file)

Macro: setdocs &body PAIRS
Package

trivial-main-thread

Source

documentation.lisp (file)


Previous: , Up: Internal definitions   [Contents][Index]

5.2.2 Functions

Function: runner-starter RUNNER
Package

trivial-main-thread

Source

main-thread.lisp (file)


Previous: , Up: Top   [Contents][Index]

Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts

Jump to:   F   L   T  
Index Entry  Section

F
File, Lisp, trivial-main-thread.asd: The trivial-main-thread<dot>asd file
File, Lisp, trivial-main-thread/documentation.lisp: The trivial-main-thread/documentation<dot>lisp file
File, Lisp, trivial-main-thread/main-thread.lisp: The trivial-main-thread/main-thread<dot>lisp file
File, Lisp, trivial-main-thread/package.lisp: The trivial-main-thread/package<dot>lisp file

L
Lisp File, trivial-main-thread.asd: The trivial-main-thread<dot>asd file
Lisp File, trivial-main-thread/documentation.lisp: The trivial-main-thread/documentation<dot>lisp file
Lisp File, trivial-main-thread/main-thread.lisp: The trivial-main-thread/main-thread<dot>lisp file
Lisp File, trivial-main-thread/package.lisp: The trivial-main-thread/package<dot>lisp file

T
trivial-main-thread.asd: The trivial-main-thread<dot>asd file
trivial-main-thread/documentation.lisp: The trivial-main-thread/documentation<dot>lisp file
trivial-main-thread/main-thread.lisp: The trivial-main-thread/main-thread<dot>lisp file
trivial-main-thread/package.lisp: The trivial-main-thread/package<dot>lisp file

Jump to:   F   L   T  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

Jump to:   %  
C   E   F   M   R   S   W  
Index Entry  Section

%
%ensure-mt: Internal macros

C
call-in-main-thread: Exported functions

E
ensure-main-runner: Exported functions
ensure-main-runner-started: Exported functions

F
find-main-thread: Exported functions
Function, call-in-main-thread: Exported functions
Function, ensure-main-runner: Exported functions
Function, ensure-main-runner-started: Exported functions
Function, find-main-thread: Exported functions
Function, runner-starter: Internal functions
Function, schedule-task: Exported functions
Function, start-main-runner: Exported functions
Function, stop-main-runner: Exported functions
Function, swap-main-thread: Exported functions

M
Macro, %ensure-mt: Internal macros
Macro, setdocs: Internal macros
Macro, with-body-in-main-thread: Exported macros

R
runner-starter: Internal functions

S
schedule-task: Exported functions
setdocs: Internal macros
start-main-runner: Exported functions
stop-main-runner: Exported functions
swap-main-thread: Exported functions

W
with-body-in-main-thread: Exported macros

Jump to:   %  
C   E   F   M   R   S   W  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.3 Variables

Jump to:   *  
S  
Index Entry  Section

*
*main-thread*: Exported special variables
*runner*: Exported special variables

S
Special Variable, *main-thread*: Exported special variables
Special Variable, *runner*: Exported special variables

Jump to:   *  
S  

Previous: , Up: Indexes   [Contents][Index]

A.4 Data types

Jump to:   P   S   T  
Index Entry  Section

P
Package, trivial-main-thread: The trivial-main-thread package

S
System, trivial-main-thread: The trivial-main-thread system

T
trivial-main-thread: The trivial-main-thread system
trivial-main-thread: The trivial-main-thread package

Jump to:   P   S   T