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



\section{library(mqi)}

\label{sec:mqi}

\begin{description}
    \predicate[semidet]{mqi_start}{1}{+Options:list}
Starts a Prolog Machine Query Interface ('MQI') using \arg{Options}. The MQI is normally started automatically by a library built for a particular programming language such as the \const{swiplserver} Python library (\secref{mqi-python-installation}), but starting manually can be useful when debugging Prolog code in some scenarios. See the documentation on "Standalone Mode" (\secref{mqi-standalone-mode}) for more information.

Once started, the MQI listens for TCP/IP or Unix Domain Socket connections and authenticates them using the password provided (or created depending on options) before processing any messages. The messages processed by the MQI are described below (\secref{mqi-messages}).

For debugging, the server outputs traces using the \predref{debug}{3} predicate so that the server operation can be observed by using the \predref{debug}{1} predicate. Run the following commands to see them:

\begin{itemize}
    \item \verb$debug(mqi(protocol))$: Traces protocol messages to show the flow of commands and connections. It is designed to avoid filling the screen with large queries and results to make it easier to read.
    \item \verb$debug(mqi(query))$: Traces messages that involve each query and its results. Therefore it can be quite verbose depending on the query.
__\arg{Options}__

\arg{Options} is a list containing any combination of the following options. When used in the Prolog top level (i.e. in Standalone Mode (\secref{mqi-standalone-mode})), these are specified as normal Prolog options like this:

\begin{code}
mqi_start([unix_domain_socket(Socket), password('a password')])
\end{code}

When using "Embedded Mode" (\secref{mqi-embedded-mode}) they are passed using the same name but as normal command line arguments like this:

\begin{code}
swipl --quiet -g mqi_start -t halt -- --write_connection_values=true
--password="a password" --create_unix_domain_socket=true
\end{code}

Note the use of quotes around values that could confuse command line
processing like spaces (e.g. "a password") and that
\verb$unix_domain_socket(Variable)$ is written as
\verb$--create_unix_domain_socket=true$ on the command line. See below for
more information.
    \item port(?Port)
The TCP/IP port to bind to on localhost. This option is ignored if the \predref{unix_domain_socket}{1} option is set. Port is either a legal TCP/IP port number (integer) or a variable term like \arg{Port}. If it is a variable, it causes the system to select a free port and unify the variable with the selected port as in \predref{tcp_bind}{2}. If the option \verb$write_connection_values(true)$ is set, the selected port is output to STDOUT followed by \verb$\n$ on startup to allow the client language library to retrieve it in "Embedded Mode" (\secref{mqi-embedded-mode}).
    \item unix_domain_socket(?Unix_Domain_Socket_Path_And_File)
If set, Unix Domain Sockets will be used as the way to communicate with the server. \arg{Unix_Domain_Socket_Path_And_File} specifies the fully qualified path and filename to use for the socket.

To have one generated instead (recommended), pass \arg{Unix_Domain_Socket_Path_And_File} as a variable when calling from the Prolog top level and the variable will be unified with a created filename. If launching in "Embedded Mode" (\secref{mqi-embedded-mode}), instead pass \verb$--create_unix_domain_socket=true$ since there isn't a way to specify variables from the command line. When generating the file, a temporary directory will be created using \predref{tmp_file}{2} and a socket file will be created within that directory following the below requirements. If the directory and file are unable to be created for some reason, \predref{mqi_start}{1} fails.

Regardless of whether the file is specified or generated, if the option \verb$write_connection_values(true)$ is set, the fully qualified path to the generated file is output to STDOUT followed by \verb$\n$ on startup to allow the client language library to retrieve it.

Specifying a file to use should follow the same guidelines as the generated file:

\begin{itemize}
    \item If the file exists when the MQI is launched, it will be deleted.
    \item The Prolog process will attempt to create and, if Prolog exits cleanly, delete this file (and directory if it was created) when the MQI closes. This means the directory from a specified file must have the appropriate permissions to allow the Prolog process to do so.
    \item For security reasons, the filename should not be predictable and the directory it is contained in should have permissions set so that files created are only accessible to the current user.
    \item The path must be below 92 \textbf{bytes} long (including null terminator) to be portable according to the Linux documentation.
\end{itemize}

    \item password(?Password)
The password required for a connection. If not specified (recommended), the MQI will generate one as a Prolog string type since Prolog atoms are globally visible (be sure not to convert to an atom for this reason). If \arg{Password} is a variable it will be unified with the created password. Regardless of whether the password is specified or generated, if the option \verb$write_connection_values(true)$ is set, the password is output to STDOUT followed by \verb$\n$ on startup to allow the client language library to retrieve it. This is the recommended way to integrate the MQI with a language as it avoids including the password as source code. This option is only included so that a known password can be supplied for when the MQI is running in Standalone Mode.
    \item \verb$query_timeout(+Seconds)$
Sets the default time in seconds that a query is allowed to run before it is cancelled. This can be overridden on a query by query basis. If not set, the default is no timeout (\verb$-1$).
    \item \verb$pending_connections(+Count)$
Sets the number of pending connections allowed for the MQI as in \predref{tcp_listen}{2}. If not provided, the default is \verb$5$.
    \item \verb$run_server_on_thread(+Run_Server_On_Thread)$
Determines whether \predref{mqi_start}{1} runs in the background on its own thread or blocks until the MQI shuts down. Must be missing or set to \const{true} when running in "Embedded Mode" (\secref{mqi-embedded-mode}) so that the SWI Prolog process can exit properly. If not set, the default is \const{true}.
    \item server_thread(?Server_Thread)
Specifies or retrieves the name of the thread the MQI will run on if \verb$run_server_on_thread(true)$. Passing in an atom for Server_Thread will only set the server thread name if \verb$run_server_on_thread(true)$. If \arg{Server_Thread} is a variable, it is unified with a generated name.
    \item \verb$write_connection_values(+Write_Connection_Values)$
Determines whether the server writes the port (or generated Unix Domain Socket) and password to STDOUT as it initializes. Used by language libraries to retrieve this information for connecting. If not set, the default is \const{false}.
    \item \verb$write_output_to_file(+File)$
Redirects STDOUT and STDERR to the file path specified. Useful for debugging the MQI when it is being used in "Embedded Mode" (\secref{mqi-embedded-mode}). If using multiple MQI instances in one SWI Prolog instance, only set this on the first one. Each time it is set the output will be redirected.
\end{itemize}

    \predicate[det]{mqi_version}{2}{?Major_Version, ?Minor_Version}
Provides the major and minor version number of the protocol used by the MQI.
The protocol includes the message format and the messages that can
be sent and received from the MQI.

Note that the initial version of the MQI did not have a version predicate so
The proper way for callers to check the version is:

\verb$use_module(library(mqi))$,
( \verb$current_predicate(mqi_version/2)$
\Sifthen{} \verb$mqi_version(Major_Version, Minor_Version)$
; \arg{Major_Version} = 0, \arg{Minor_Version} = 0
)

Major versions are increased when there is a change to the protocol that will
likely break clients written to the previous version. Minor versions are increased
when there is new functionality that will \textbf{not} break clients written to the old version

This allows a client written to MQI version 'Client_Major_Version.Client_Minor_Version'
to check for non-breaking compatibility like this:

Client_Major_Version = MQI_Major_Version and Client_Minor_Version \Sel{} MQI_Minor_Version

Breaking changes (i.e. Major version increments) should be very rare as the goal is to
have the broadest adoption possible.

Protocol Version History:

\begin{itemize}
    \item 0.0 First published version. Had a protocol bug that required messages sent to MQI to
count Unicode code points instead of bytes for the message header.
    \item 1.0 Breaking change: Fixed protocol bug so that it properly accepted byte count instead of Unicode code point
count in the message header for messages sent to MQI.
\end{itemize}

    \predicate[semidet]{mqi_start}{0}{}
Main entry point for running the Machine Query Interface in
"Embedded Mode" (\secref{mqi-embedded-mode}) and designed to be called from
the command line. Embedded Mode is used when launching the Machine
Query Interface as an embedded part of another language (e.g.
Python). Calling \predref{mqi_start}{0} from Prolog interactively is not
recommended as it depends on Prolog exiting to stop the MQI, instead
use \predref{mqi_start}{1} for interactive use.

To launch embedded mode:

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

This will start SWI Prolog and invoke the \predref{mqi_start}{0} predicate and
exit the process when that predicate stops. Any command line
arguments after the standalone \verb$--$ will be passed as Options. These
are the same Options that \predref{mqi_start}{1} accepts and are passed to it
directly. Some options are expressed differently due to command line
limitations, see \predref{mqi_start}{1} Options for more information.

Any Option values that cause issues during command line parsing (such
as spaces) should be passed with \verb$""$ like this:

\begin{code}
swipl --quiet -g mqi_start -t halt -- --write_connection_values=true \
                                      --password="HGJ SOWLWW WNDSJD"
\end{code}

For help on commandline options run

\begin{code}
swipl -g mqi_start -- --help
\end{code}

    \predicate[det]{mqi_stop}{1}{?Server_Thread_ID:atom}
If \arg{Server_Thread_ID} is a variable, stops all Machine Query Interfaces and associated threads. If \arg{Server_Thread_ID} is an atom, then only the MQI with that \arg{Server_Thread_ID} is stopped. \arg{Server_Thread_ID} can be provided or retrieved using \arg{Options} in \predref{mqi_start}{1}.

Always succeeds.
\end{description}