
threadutil.pl -- Interactive thread utilities
This library provides utilities that are primarily intended for interactive usage in a threaded Prolog environment. It allows for inspecting threads, manage I/O of background threads (depending on the environment) and manipulating the debug status of threads.
threads
- List currently known threads with their status.
join_threads
- Join all terminated threads.
with_stopped_threads(:Goal, Options) is det
- Stop all threads except the caller while running
once(Goal)
. Note that this is in the thread user utilities as this is not something that should be used by normal applications. Notably, this may deadlock if the current thread requires input from some other thread to complete Goal or one of the stopped threads has a lock. Options:- stop_nodebug_threads(+Boolean)
- If
true
(defaultfalse
), also stop threads created with thedebug(false)
option. - except(+List)
- Do not stop threads from this list.
thread_has_console is semidet
- True when the calling thread has an attached console.
open_console(+Title, -In, -Out, -Err) is det[private]
- Open a new console window and unify In, Out and Err with the input, output and error streams for the new console. This predicate is only available if win_open_console/5 (Windows or Qt swipl-win) or '$open_xterm'/5 (POSIX systems with pseudo terminal support).
xterm_args(-List) is nondet[multifile]
- Multifile and dynamic hook that provides (additional) arguments for
the
xterm(1)
process opened for additional thread consoles. Each solution must bind List to a list of atomic values. All solutions are concatenated using append/2 to form the final argument list.The defaults set the colors to black-on-light-yellow, enable a scrollbar, set the font using Xft font pattern and prepares the back-arrow key.
attach_console is det
attach_console(?Title) is det
- Create a new console and make the standard Prolog streams point to it. If not provided, the title is built using the thread id. Does nothing if the current thread already has a console attached.
enable_line_editing(+In, +Out, +Err) is det[private]
- Enable line editing for the console. This is by built-in for the
Windows console. We can also provide it for the X11
xterm(1)
based console if we use the BSD libedit based command line editor. detach_console(+ThreadId) is det[private]
- Destroy the console for ThreadId.
interactor is det
interactor(?Title) is det
- Run a Prolog toplevel in another thread with a new console window. If Title is given, this will be used as the window title.
thread_run_interactor
- Attach a console and run a Prolog toplevel in the current thread.
tspy(:Spec) is det
tspy(:Spec, +ThreadId) is det
- Trap the graphical debugger on reaching Spec in the specified or any thread.
tdebug is det
tdebug(+Thread) is det
- Enable debug-mode, trapping the graphical debugger on reaching spy-points or errors.
tnodebug is det
tnodebug(+Thread) is det
- Disable debug-mode in all threads or the specified Thread.
tbacktrace(+Thread) is det
tbacktrace(+Thread, +Options) is det
- Print a backtrace for Thread to the stream
user_error
of the calling thread. This is achieved by inserting an interrupt into Thread using call_in_thread/2. Options:- depth(+MaxFrames)
- Number of stack frames to show. Default is the current Prolog
flag
backtrace_depth
or 20.
Other options are passed to get_prolog_backtrace/3.
thread_get_prolog_backtrace(+Depth, -Stack, +Options)[private]
- As get_prolog_backtrace/3, but starts above the C callback, hiding the overhead inside call_in_thread/2.
tprofile(+Thread) is det
- Profile the operation of Thread until the user hits a key.
init_pce[private]
- Make sure XPCE is running if it is attached, so we can use the graphical display using in_pce_thread/1.
Re-exported predicates
The following predicates are exported from this file while their implementation is defined in imported modules or non-module files loaded by this module.
attach_console is det
attach_console(?Title) is det
- Create a new console and make the standard Prolog streams point to it. If not provided, the title is built using the thread id. Does nothing if the current thread already has a console attached.
interactor is det
interactor(?Title) is det
- Run a Prolog toplevel in another thread with a new console window. If Title is given, this will be used as the window title.
tspy(:Spec) is det
tspy(:Spec, +ThreadId) is det
- Trap the graphical debugger on reaching Spec in the specified or any thread.
tdebug is det
tdebug(+Thread) is det
- Enable debug-mode, trapping the graphical debugger on reaching spy-points or errors.
tnodebug is det
tnodebug(+Thread) is det
- Disable debug-mode in all threads or the specified Thread.
tbacktrace(+Thread) is det
tbacktrace(+Thread, +Options) is det
- Print a backtrace for Thread to the stream
user_error
of the calling thread. This is achieved by inserting an interrupt into Thread using call_in_thread/2. Options:- depth(+MaxFrames)
- Number of stack frames to show. Default is the current Prolog
flag
backtrace_depth
or 20.
Other options are passed to get_prolog_backtrace/3.