% This LaTeX document was generated using the LaTeX backend of PlDoc,
% The SWI-Prolog documentation system



\section{Machine Query Interface Overview}

\label{sec:mqi-overview}

The SWI Prolog Machine Query Interface ('MQI') is designed to enable embedding SWI Prolog into just about any programming language (Python, Go, C\#, etc) in a straightforward way. It is designed for scenarios that need to use SWI Prolog as a local implementation detail of another language. Think of it as running SWI Prolog "like a library". It can support any programming language that can launch processes, read their STDOUT pipe, and send and receive JSON over TCP/IP. A Python 3 library is included as a part of SWI Prolog, see Installation Steps for Python (\secref{mqi-python-installation}).

Key features of the MQI:

\begin{itemize}
    \item Simulates the familiar Prolog "top level" (i.e. the interactive prompt you get when running Prolog: "\Sdirective{}").
    \item Always runs queries from a connection on a consistent, single thread for that connection. The application itself can still be multi-threaded by running queries that use the multi-threading Prolog predicates or by opening more than one connection.
    \item Runs as a separate dedicated \textbf{local} Prolog process to simplify integration (vs. using the C-level SWI Prolog interface). The process is launched and managed by a specific running client (e.g. Python or other language) program.
    \item Communicates using sockets and \href{https://www.json.org/}{JSON} encoded as UTF-8 to allow it to work on any platform supported by SWI Prolog. For security reasons, only listens on TCP/IP localhost or Unix Domain Sockets and requires (or generates depending on the options) a password to open a connection.
    \item Has a lightweight text-based message format with only 6 commands: run synchronous query, run asynchronous query, retrieve asynchronous results, cancel asynchronous query, close connection and terminate the session.
    \item Communicates answers using \href{https://www.json.org/}{JSON}, a well-known data format supported by most languages natively or with generally available libraries.
\end{itemize}

The server can be used in two different modes:

\begin{itemize}
    \item \textbf{Embedded mode}: This is the main use case for the MQI. The user uses a library (just like any other library in their language of choice). That library integrates the MQI by launching the SWI Prolog process, connecting to it, and wrapping the MQI protocol with a language specific interface.
    \item \textbf{Standalone mode}: The user still uses a library as above, but launches SWI Prolog independently of the language. The client language library connects to that process. This allows the user to see, interact with, and debug the Prolog process while the library interacts with it.
\end{itemize}

Note that the MQI is related to the \href{https://www.swi-prolog.org/pldoc/man?section=pengine-references}{Pengines library}, but where the Pengines library is focused on a client/server, multi-tenet, sandboxed environment, the MQI is local, single tenet and unconstrained. Thus, when the requirement is to embed Prolog within another programming language "like a library", it can be a good solution for exposing the full power of Prolog with low integration overhead.

\subsection{Installation Steps for Python}

\label{sec:mqi-python-installation}

A Python 3.x library that integrates Python with SWI Prolog using the Machine Query Interface is included within the \const{libs} directory of the SWI Prolog installation. It is also available using \verb$pip install swiplserver$. See the \href{https://www.swi-prolog.org/packages/mqi/prologmqi.html}{Python swiplserver library documentation} for more information on how to use and install it from either location.

\subsection{Installation Steps for Other Languages}

\label{sec:mqi-language-installation}

In general, to use the Machine Query Interface with any programming language:

\begin{enumerate}
    \item Install SWI Prolog itself on the machine the application will run on.
    \item Check if your SWI Prolog version includes the MQI by launching it and typing \verb$?- mqi_start([]).$ If it can't find it, see below for how to install it.
    \item Ensure that the system path includes a path to the \const{swipl} executable from that installation.
    \item Make sure the application (really the user that launches the application) has permission to launch the SWI Prolog process. Unless your system is unusually locked down, this should be allowed by default. If not, you'll need to set the appropriate permissions to allow this.
    \item Install (or write!) the library you'll be using to access the MQI in your language of choice.
\end{enumerate}

If your SWI Prolog version doesn't yet include the MQI:

\begin{enumerate}
    \item Download the \verb$mqi.pl$ file from the \href{https://github.com/SWI-Prolog/packages-mqi/blob/master/mqi.pl}{GitHub repository}.
    \item Open an operating system command prompt and go to the directory where you downloaded \verb$mqi.pl$.
    \item Run the command below. On Windows the command prompt must be \href{https://www.wikihow.com/Run-Command-Prompt-As-an-Administrator-on-Windows}{run as an administrator}. On Mac or Linux, start the command with \const{sudo} as in \verb$sudo swipl -s ...$.
\end{enumerate}

\begin{code}
swipl -s mqi.pl -g "mqi:install_to_library('mqi.pl')" -t halt
\end{code}

\subsection{Prolog Language Differences from the Top Level}

\label{sec:mqi-toplevel-differences}

The Machine Query Interface is designed to act like using the \href{https://www.swi-prolog.org/pldoc/man?section=quickstart}{"top level"} prompt of SWI Prolog itself (i.e. the "\Sdirective{}" prompt). If you've built the Prolog part of your application by loading code, running it and debugging it using the normal SWI Prolog top level, integrating it with your native language should be straightforward: simply run the commands you'd normally run on the top level, but now run them using the query APIs provided by the library built for your target language. Those APIs will allow you to send the exact same text to Prolog and they should execute the same way. Here's an example using the Python \const{swiplserver} library:

\begin{code}
% Prolog Top Level
?- member(X, [first, second, third]).
X = first ;
X = second ;
X = third.
\end{code}

\begin{code}
# Python using the swiplserver library
from swiplserver import PrologMQI, PrologThread

with PrologMQI() as mqi:
    with mqi.create_thread() as prolog_thread:
        result = prolog_thread.query("member(X, [first, second, third]).")
        print(result)

first
second
third
\end{code}

While the query functionality of the MQI does run on a thread, it will always be the \textbf{same} thread, and, if you use a single connection, it will only allow queries to be run one at a time, just like the top level. Of course, the queries you send can launch threads, just like the top level, so you are not limited to a single threaded application. There are a few differences from the top level, however:

\begin{itemize}
    \item Normally, the SWI Prolog top level runs all user code in the context of a built-in module called "user", as does the MQI. However, the top level allows this to be changed using the \predref{module}{1} predicate. This predicate has no effect when sent to the MQI.
    \item Predefined streams like \verb$user_input$ are initially bound to the standard operating system I/O streams (like STDIN) and, since the Prolog process is running invisibly, will obviously not work as expected. Those streams can be changed, however, by issuing commands using system predicates as defined in the SWI Prolog documentation.
    \item Every connection to the MQI runs in its own thread, so opening two connections from an application means you are running multithreaded code.
    \item The SWI Prolog top level does special handling to make residual \href{https://www.swi-prolog.org/pldoc/man?section=attvar}{attributes on variables} print out in a human-friendly way. MQI instead returns any residuals in a special variable called \verb|$residuals| that is added to the results.
    \item Some Prolog extensions do not provide the full answer to a query by means of the variable bindings. The top level does extra work to find where the answers are stored and print them out. All of these extensions have an interface to get to this data as a Prolog term and users of MQI need to do this work themselves. Examples include: \href{https://www.swi-prolog.org/pldoc/man?section=chr}{Constraint Handling Rules (CHR)} stores constraints in global variables, \href{https://www.swi-prolog.org/pldoc/man?section=wfs-toplevel}{Well Founded Semantics} has the notion of delayed, which is translated into a program that carries the inconsistency if there are conflicting negations, \href{https://www.swi-prolog.org/pack/list?p=scasp}{\const{s(CASP)}} has a model and justification.
\end{itemize}

A basic rule to remember is: any predicates designed to interact with or change the default behavior of the top level itself probably won't have any effect.

\subsection{Embedded Mode: Integrating the Machine Query Interface Into a New Programming Language}

\label{sec:mqi-embedded-mode}

The most common way to use the Machine Query Interface is to find a library that wraps and exposes it as a native part of another programming language such as the Python \verb$swiplserver$ library (\secref{mqi-python-installation}). This section describes how to build one if there isn't yet a library for your language. To do this, you'll need to familiarize yourself with the MQI protocol as described in the \predref{mqi_start}{1} documentation. However, to give an idea of the scope of work required, below is a typical interaction done (invisibly to the user) in the implementation of any programming language library:

\begin{enumerate}
    \item Launch the SWI Prolog process using (along with any other options the user requests): \verb$swipl --quiet -g mqi_start -t halt -- --write_connection_values=true$. To work, the \const{swipl} Prolog executable will need to be on the path or the path needs to be specified in the command. This launches SWI Prolog, starts the MQI, and writes the chosen port and password to STDOUT. This way of launching invokes the \predref{mqi_start}{0} predicate that turns off the \const{int} (i.e. Interrupt/SIGINT) signal to Prolog. This is because some languages (such as Python) use that signal during debugging and it would be otherwise passed to the client Prolog process and switch it into the debugger. See the \predref{mqi_start}{0} predicate for more information on other command line options.
    \item Read the SWI Prolog STDOUT to retrieve the TCP/IP port and password. They are sent in that order, delimited by '\Bn{}'.
\end{enumerate}

\begin{code}
$ swipl --quiet -g mqi_start -t halt -- --write_connection_values=true
54501
185786669688147744015809740744888120144
\end{code}

Now the server is started. To create a connection:

\begin{enumerate}
    \item Use the language's TCP/IP sockets library to open a socket on the specified port of localhost and send the password as a message. Messages to and from the MQI are in the form \verb$<stringByteLength>.\n<stringBytes>.\n $ where \const{stringByteLength} includes the \verb$.\n$ from the string. For example: \verb$7.\nhello.\n$ More information on the message format (\secref{mqi-message-format}) is below.
    \item Listen on the socket for a response message of \verb$true([[threads(Comm_Thread_ID, Goal_Thread_ID), version(Major, Minor)]])$ (which will be in JSON form) indicating successful creation of the connection. \arg{Comm_Thread_ID} and \arg{Goal_Thread_ID} are the internal Prolog IDs of the two threads that are used for the connection. They are sent solely for monitoring and debugging purposes. \const{version} was introduced in version 1.0 of the protocol to allow for detecting the protocol version and should be checked to ensure the protocol version is supported by your library. See \predref{mqi_version}{2} for more information and a version history.
\end{enumerate}

We can try all of this using the Unix tool \const{nc} (netcat) (also available for Windows) to interactively connect to the MQI. In \const{nc} hitting \const{enter} sends \verb$\n$ which is what the message format requires. The server responses are show indented inline.

We'll use the port and password that were sent to STDOUT above:

\begin{code}
$ nc 127.0.0.1 54501
41.
185786669688147744015809740744888120144.
    173.
    {
      "args": [
        [
          [
        {
          "args": ["mqi1_conn2_comm", "mqi1_conn2_goal" ],
          "functor":"threads"
        },
        {
          "args": ["1", "0" ],
          "functor":"version"
        }
          ]
        ]
      ],
      "functor":"true"
    }
\end{code}

Now the connection is established. To run queries and shutdown:

\begin{enumerate}
    \item Any of the messages described in the Machine Query Interface messages documentation (\secref{mqi-messages}) can now be sent to run queries and retrieve their answers. For example, send the message \verb$run(atom(a), -1)$ to run the synchronous query \verb$atom(a)$ with no timeout and wait for the response message. It will be \verb$true([[]])$ (in JSON form).
    \item Shutting down the connection is accomplished by sending the message \const{close}, waiting for the response message of \verb$true([[]])$ (in JSON form), and then closing the socket using the socket API of the language. If the socket is closed (or fails) before the \const{close} message is sent, the default behavior of the MQI is to exit the SWI Prolog process to avoid leaving the process around. This is to support scenarios where the user is running and halting their language debugger without cleanly exiting.
    \item Shutting down the launched SWI Prolog process is accomplished by sending the \const{quit} message and waiting for the response message of \verb$true([[]])$ (in JSON form). This will cause an orderly shutdown and exit of the process.
\end{enumerate}

Continuing with the \const{nc} session (the \const{quit} message isn't shown since the \const{close} message closes the connection):

\begin{code}
18.
run(atom(a), -1).
    39.
    {"args": [ [ [] ] ], "functor":"true"}
7.
close.
    39.
    {"args": [ [ [] ] ], "functor":"true"}
\end{code}

Note that Unix Domain Sockets can be used instead of a TCP/IP port. How
to do this is described with \predref{mqi_start}{1}.

Here's the same example running in the R language. Note that this is \textbf{not} an example of how to use the MQI from R, it just shows the first code a developer would write as they begin to build a nice library to connect R to Prolog using the MQI:

\begin{code}
# Server run with: swipl mqi.pl --port=40001 --password=123
# R Source
print("# Establish connection")

sck = make.socket('localhost', 40001)

print("# Send password")

write.socket(sck, '5.\n') # message length

write.socket(sck, '123.\n') # password

print(read.socket(sck))

print("# Run query")

query = 'run(member(X, [1, 2, 3]), -1).\n'

write.socket(sck, paste(nchar(query), '.\n', sep='')) # message length

write.socket(sck, query) # query

print(read.socket(sck))

print("# Close session")

close.socket(sck)
\end{code}

And here's the output:

\begin{code}
[1] "# Establish connection"

[1] "# Send password"

[1] "172.\n{\n "args": [\n [\n [\n\t{\n\t "args": ["mqi1_conn1_comm", "mqi1_conn1_goal" ],\n\t "functor":"threads"\n\t}\n ]\n ]\n ],\n "functor":"true"\n}"

[1] "# Run query"

[1] "188.\n{\n "args": [\n [\n [ {"args": ["X", 1 ], "functor":"="} ],\n [ {"args": ["X", 2 ], "functor":"="} ],\n [ {"args": ["X", 3 ], "functor":"="} ]\n ]\n ],\n "functor":"true"\n}"

[1] "# Close session"
\end{code}

Other notes about creating a new library to communicate with the MQI:

\begin{itemize}
    \item Where appropriate, use similar names and approaches to the \href{https://github.com/SWI-Prolog/packages-mqi/tree/master/python}{Python library} when designing your language library. This will give familiarity and faster learning for users that use more than one language.
    \item Use the \predref{debug}{1} predicate described in the \predref{mqi_start}{1} documentation to turn on debug tracing. It can really speed up debugging.
    \item Read the STDOUT and STDERR output of the SWI Prolog process and output them to the debugging console of the native language to help users debug their Prolog application.
\end{itemize}

\subsection{Standalone Mode: Debugging Prolog Code Used in an Application}

\label{sec:mqi-standalone-mode}

When using the Machine Query Interface from another language, debugging the Prolog code itself can often be done by viewing traces from the Prolog native \predref{writeln}{1} or \predref{debug}{3} predicates. Their output will be shown in the debugger of the native language used. Sometimes an issue surfaces deep in an application. When this happens, running the application in the native language while setting breakpoints and viewing traces in Prolog itself is often the best debugging approach. Standalone mode is designed for this scenario.

As the MQI is a multithreaded application, debugging the running code requires using the multithreaded debugging features of SWI Prolog as described in the section on \href{https://www.swi-prolog.org/pldoc/man?section=threaddebug}{"Debugging Threads"} in the SWI Prolog documentation. A typical flow for Standalone Mode is:

\begin{enumerate}
    \item Launch SWI Prolog and call the \predref{mqi_start}{1} predicate specifying a port and password. Use the \predref{tdebug}{0} predicate to set all threads to debugging mode like this: \verb$tdebug, mqi_start([port(4242), password(debugnow)])$.
    \item Set the port and password in the initialization API in the native language being used.
    \item Launch the application and go through the steps to reproduce the issue.
\end{enumerate}

In Python this would look like:

\begin{code}
% From the SWI Prolog top level
?- tdebug, mqi_start([port(4242), password(debugnow)]).
% The graphical front-end will be used for subsequent tracing
true.
\end{code}

\begin{code}
# Python using the swiplserver library {#mqi-library}
from swiplserver import PrologMQI, PrologThread

with PrologMQI(launch_mqi=False, port=4242, password="debugnow") as mqi:
    with mqi.create_thread() as prolog_thread:
        # Your code to be debugged here
\end{code}

At this point, all of the multi-threaded debugging tools in SWI Prolog are available for debugging the problem. If the issue is an unexpected exception, the exception debugging features of SWI Prolog can be used to break on the exception and examine the state of the application. If it is a logic error, breakpoints can be set to halt at the point where the problem appears, etc.

Note that, while using an MQI library to access Prolog will normally end and restart the process between runs of the code, running the server in standalone mode doesn't clear state between launches of the application. You'll either need to relaunch between runs or build your application so that it does the initialization at startup.

\subsection{Machine Query Interface Messages}

\label{sec:mqi-messages}

The messages the Machine Query Interface responds to are described below. A few things are true for all of them:

\begin{itemize}
    \item Every connection is in its own separate thread. Opening more than one connection means the code is running concurrently.
    \item Closing the socket without sending \const{close} and waiting for a response will halt the process if running in "Embedded Mode" (\secref{mqi-embedded-mode}). This is so that stopping a debugger doesn't leave the process orphaned.
    \item All messages are request/response messages. After sending, there will be exactly one response from the MQI.
    \item Timeout in all of the commands is in seconds. Sending a variable (e.g. \arg{_}) will use the default timeout passed to the initial \predref{mqi_start}{1} predicate and \verb$-1$ means no timeout.
    \item All queries are run in the default module context of \const{user}. \predref{module}{1} has no effect.
\end{itemize}

\subsubsection{Machine Query Interface Message Format}

\label{sec:mqi-message-format}

Every Machine Query Interface message is a single valid Prolog term. Those that run queries have an argument which represents the query as a single term. To run several goals at once use \verb$(goal1, goal2, ...)$ as the goal term.

The format of sent and received messages is identical (\verb$\n$ stands for the ASCII newline character which is a single byte):

\begin{code}
<stringByteLength>.\n<stringBytes>.\n.
\end{code}

For example, to send \const{hello} as a message you would send this:

\begin{code}
7.\nhello.\n
\end{code}

\begin{itemize}
    \item \verb$<stringByteLength>$ is the number of bytes of the string to follow (including the \verb$.\n$), in human readable numbers, such as \verb$15$ for a 15 byte string. It must be followed by \verb$.\n$.
    \item \verb$<stringBytes>$ is the actual message string being sent, such as \verb$run(atom(a), -1).\n$. It must always end with \verb$.\n$. The character encoding used to decode and encode the string is UTF-8.
\end{itemize}

\begin{quote}
Important: The very first version of MQI (version 0.0) had a bug that required messages sent to (but not received from) MQI to use the count of Unicode code points (\textbf{not} bytes). This was fixed to properly require byte count in the next version, version 1.0.
\end{quote}

To send a message to the MQI, send a message using the message format above to the localhost port or Unix Domain Socket that the MQI is listening on. For example, to run the synchronous goal \verb$atom(a)$, send the following message:

\begin{code}
18.\nrun(atom(a), -1).\n<end of stream>
\end{code}

You will receive the response below on the receive stream of the same connection you sent on. Note that the answer is in JSON format. If a message takes longer than 2 seconds, there will be "heartbeat" characters (".") at the beginning of the response message, approximately 1 every 2 seconds. So, if the query takes 6 seconds for some reason, there will be three "." characters first:

\begin{code}
...12\ntrue([[]]).\n
\end{code}

\subsubsection{Machine Query Interface Messages Reference}

\label{sec:mqi-messages}

The full list of Machine Query Interface messages is described below:

\begin{description}
    \termitem{run}{Goal, Timeout}
Runs \arg{Goal} on the connection's designated query thread. Stops accepting new commands until the query is finished and it has responded with the results. If a previous query is still in progress, waits until the previous query finishes (discarding that query's results) before beginning the new query.

\arg{Timeout} is in seconds and indicates a timeout for generating all results for the query. Sending a variable (e.g. \arg{_}) will use the default timeout passed to the initial \predref{mqi_start}{1} predicate and \verb$-1$ means no timeout.

While it is waiting for the query to complete, sends a "." character \textbf{not} in message format, just as a single character, once every two seconds to proactively ensure that the client is alive. Those should be read and discarded by the client.

If a communication failure happens (during a heartbeat or otherwise), the connection is terminated, the query is aborted and (if running in "Embedded Mode" (\secref{mqi-embedded-mode})) the SWI Prolog process shuts down.

When completed, sends a response message using the normal message format indicating the result.

Response:

\begin{quote}
\begin{tabulary}{0.9\textwidth}{|l|L|}
\hline
\verb$true([Answer1, Answer2, ... ])$ & The goal succeeded at least once. The response always includes all answers as if run with \verb$findall()$ (see \predref{run_async}{3} below to get individual results back iteratively). Each \arg{Answer} is a list of the assignments of free variables in the answer. A special variable called \verb|$residuals| will be added to each answer that has residual \href{https://www.swi-prolog.org/pldoc/man?section=attvar}{variable constraints on it}. This will contain a list of all the constraints on all the variables for that answer. If there are no free variables, \arg{Answer} is an empty list. \\
\const{false} & The goal failed. \\
\verb$exception(time_limit_exceeded)$ & The query timed out. \\
\verb$exception(Exception)$ & An arbitrary exception was not caught while running the goal. \\
\verb$exception(connection_failed)$ & The query thread unexpectedly exited. The MQI will no longer be listening after this exception. \\
\hline
\end{tabulary}
\end{quote}

    \termitem{run_async}{Goal, Timeout, Find_All}
Starts a Prolog query specified by \arg{Goal} on the connection's designated query thread. Answers to the query, including exceptions, are retrieved afterwards by sending the \verb$async_result$ message (described below). The query can be cancelled by sending the \verb$cancel_async$ message. If a previous query is still in progress, waits until that query finishes (discarding that query's results) before responding.

\arg{Timeout} is in seconds and indicates a timeout for generating all results for the query. Sending a variable (e.g. \arg{_}) will use the default timeout passed to the initial \predref{mqi_start}{1} predicate and \verb$-1$ means no timeout.

If the socket closes before a response is sent, the connection is terminated, the query is aborted and (if running in "Embedded Mode" (\secref{mqi-embedded-mode})) the SWI Prolog process shuts down.

If it needs to wait for the previous query to complete, it will send heartbeat messages (see "Machine Query Interface Message Format" (\secref{mqi-message-format})) while it waits. After it responds, however, it does not send more heartbeats. This is so that it can begin accepting new commands immediately after responding so the client.

\verb$Find_All == true$ means generate one response to an \verb$async_result$ message with all of the answers to the query (as in the \const{run} message above). \verb$Find_All == false$ generates a single response to an \verb$async_result$ message per answer.

Response:

\begin{quote}
\begin{tabulary}{0.9\textwidth}{|l|L|}
\hline
\verb$true([[]])$ & The goal was successfully parsed. \\
\verb$exception(Exception)$ & An error occurred parsing the goal. \\
\verb$exception(connection_failed)$ & The goal thread unexpectedly shut down. The MQI will no longer be listening after this exception. \\
\hline
\end{tabulary}
\end{quote}

    \termitem{cancel_async}{}
Attempt to cancel a query started by the \verb$run_async$ message in a way that allows further queries to be run on this Prolog thread afterwards.

If there is a goal running, injects a \verb$throw(cancel_goal)$ into the executing goal to attempt to stop the goal's execution. Begins accepting new commands immediately after responding. Does not inject \predref{abort}{0} because this would kill the connection's designated thread and the system is designed to maintain thread local data for the client. This does mean it is a "best effort" cancel since the exception can be caught.

\verb$cancel_async$ is guaranteed to either respond with an exception (if there is no query or pending results from the last query), or safely attempt to stop the last executed query even if it has already finished.

To guarantee that a query is cancelled, send \const{close} and close the socket.

It is not necessary to determine the outcome of \verb$cancel_async$ after sending it and receiving a response. Further queries can be immediately run. They will start after the current query stops.

However, if you do need to determine the outcome or determine when the query stops, send \verb$async_result$. Using \verb$Timeout = 0$ is recommended since the query might have caught the exception or still be running. Sending \verb$async_result$ will find out the "natural" result of the goal's execution. The "natural" result depends on the particulars of what the code actually did. The response could be:

\begin{quote}
\begin{tabulary}{0.9\textwidth}{|l|L|}
\hline
\verb$exception(cancel_goal)$ & The query was running and did not catch the exception. I.e. the goal was successfully cancelled. \\
\verb$exception(time_limit_exceeded)$ & The query timed out before getting cancelled. \\
\verb$exception(Exception)$ & They query hits another exception before it has a chance to be cancelled. \\
A valid answer & The query finished before being cancelled. \\
\hline
\end{tabulary}
\end{quote}

Note that you will need to continue sending \verb$async_result$ until you receive an \verb$exception(Exception)$ message if you want to be sure the query is finished (see documentation for \verb$async_result$).

Response:

\begin{quote}
\begin{tabulary}{0.9\textwidth}{|l|L|}
\hline
\verb$true([[]])$ & There is a query running or there are pending results for the last query. \\
\verb$exception(no_query)$ & There is no query or pending results from a query to cancel. \\
\verb$exception(connection_failed)$ & The connection has been unexpectedly shut down. The MQI will no longer be listening after this exception. \\
\hline
\end{tabulary}
\end{quote}

    \termitem{async_result}{Timeout}
Get results from a query that was started via a \verb$run_async$ message. Used to get results for all cases: if the query terminates normally, is cancelled by sending a \verb$cancel_async$ message, or times out.

Each response to an \verb$async_result$ message responds with one result and, when there are no more results, responds with \verb$exception(no_more_results)$ or whatever exception stopped the query. Receiving any \const{exception} response except \verb$exception(result_not_available)$ means there are no more results. If \verb$run_async$ was run with \verb$Find_All == false$, multiple \verb$async_result$ messages may be required before receiving the final exception.

Waits \arg{Timeout} seconds for a result. \verb$Timeout == -1$ or sending a variable for \arg{Timeout} indicates no timeout. If the timeout is exceeded and no results are ready, sends \verb$exception(result_not_available)$.

Some examples:

\begin{quote}
\begin{tabulary}{0.9\textwidth}{|L|L|}
\hline
If the query succeeds with N answers... & \verb$async_result$ messages 1 to N will receive each answer, in order, and \verb$async_result$ message N+1 will receive \verb$exception(no_more_results)$ \\
If the query fails (i.e. has no answers)... & \verb$async_result$ message 1 will receive \const{false} and \verb$async_result$ message 2 will receive \verb$exception(no_more_results)$ \\
If the query times out after one answer... & \verb$async_result$ message 1 will receive the first answer and \verb$async_result$ message 2 will receive \verb$exception(time_limit_exceeded)$ \\
If the query is cancelled after it had a chance to get 3 answers... & \verb$async_result$ messages 1 to 3 will receive each answer, in order, and \verb$async_result$ message 4 will receive \verb$exception(cancel_goal)$ \\
If the query throws an exception before returning any results... & \verb$async_result$ message 1 will receive \verb$exception(Exception)$ \\
\hline
\end{tabulary}
\end{quote}

Note that, after sending \verb$cancel_async$, calling \verb$async_result$ will return the "natural" result of the goal's execution. The "natural" result depends on the particulars of what the code actually did since this is multi-threaded and there are race conditions. This is described more below in the response section and above in \verb$cancel_async$.

Response:

\begin{quote}
\begin{tabulary}{0.9\textwidth}{|l|L|}
\hline
\verb$true([Answer1, Answer2, ... ])$ & The next answer from the query is a successful answer. Whether there are more than one \arg{Answer} in the response depends on the \const{findall} setting. Each \arg{Answer} is a list of the assignments of free variables in the answer. A special variable called \verb|$residuals| will be added to each answer that has residual \href{https://www.swi-prolog.org/pldoc/man?section=attvar}{variable constraints on it}. This will contain a list of all the constraints on all the variables for that answer. If there are no free variables, \arg{Answer} is an empty list. \\
\const{false} & The query failed with no answers. \\
\verb$exception(no_query)$ & There is no query in progress. \\
\verb$exception(result_not_available)$ & There is a running query and no results were available in \arg{Timeout} seconds. \\
\verb$exception(no_more_results)$ & There are no more answers and no other exception occurred. \\
\verb$exception(cancel_goal)$ & The next answer is an exception caused by \verb$cancel_async$. Indicates no more answers. \\
\verb$exception(time_limit_exceeded)$ & The query timed out generating the next answer (possibly in a race condition before getting cancelled). Indicates no more answers. \\
\verb$exception(Exception)$ & The next answer is an arbitrary exception. This can happen after \verb$cancel_async$ if the \verb$cancel_async$ exception is caught or the code hits another exception first. Indicates no more answers. \\
\verb$exception(connection_failed)$ & The goal thread unexpectedly exited. The MQI will no longer be listening after this exception. \\
\hline
\end{tabulary}
\end{quote}

    \termitem{close}{}
Closes a connection cleanly, indicating that the subsequent socket close is not a connection failure. Thus it doesn't shutdown the MQI in "Embedded Mode" (\secref{mqi-embedded-mode}). The response must be processed by the client before closing the socket or it will be interpreted as a connection failure.

Any asynchronous query that is still running will be halted by using \predref{abort}{0} in the connection's query thread.

Response:
\verb$true([[]])$
    \termitem{quit}{}
Stops the MQI and ends the SWI Prolog process. This allows client language libraries to ask for an orderly shutdown of the Prolog process.

Response:
\verb$true([[]])$
\end{description}