swiplserver
Python library (section 1.1), but
starting manually can be useful when debugging Prolog code in some
scenarios. See the documentation on "Standalone Mode" (section
1.5) 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 (section 1.6).
For debugging, the server outputs traces using the debug/3 predicate so that the server operation can be observed by using the debug/1 predicate. Run the following commands to see them:
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.debug(mqi(query)): Traces messages that involve each
query and its results. Therefore it can be quite verbose depending on
the query.
Options
Options is a list containing any combination of the following options. When used in the Prolog top level (i.e. in Standalone Mode (section 1.5)), these are specified as normal Prolog options like this:
mqi_start([unix_domain_socket(Socket), password('a password')])
When using "Embedded Mode" (section 1.4) they are passed using the same name but as normal command line arguments like this:
swipl mqi --write_connection_values=true
--password="a password" --create_unix_domain_socket=true
Note the use of quotes around values that could confuse command line
processing like spaces (e.g. "a password") and that
unix_domain_socket(Variable) is written as
--create_unix_domain_socket=true on the command line. See
below for more information.
write_connection_values(true)
is set, the selected port is output to STDOUT followed by \n
on startup to allow the client language library to retrieve it in
"Embedded Mode" (section 1.4).
To have one generated instead (recommended), pass 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"
(section 1.4), instead pass --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 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, mqi_start/1
fails.
Regardless of whether the file is specified or generated, if the
option write_connection_values(true) is set, the fully
qualified path to the generated file is output to STDOUT followed by \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:
write_connection_values(true)
is set, the password is output to STDOUT followed by \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.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 (-1).pending_connections(+Count) Sets the number of pending
connections allowed for the MQI as in tcp_listen/2.
If not provided, the default is 5.run_server_on_thread(+Run_Server_On_Thread) Determines
whether mqi_start/1 runs in the
background on its own thread or blocks until the MQI shuts down. Must be
missing or set to true when running in "Embedded Mode" (section
1.4) so that the SWI Prolog process can exit properly. If not set,
the default is true.run_server_on_thread(true).
Passing in an atom for Server_Thread will only set the server thread
name if run_server_on_thread(true). If Server_Thread
is a variable, it is unified with a generated name.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 false.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" (section
1.4). 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.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:
use_module(library(mqi)), ( current_predicate(mqi_version/2)
-> mqi_version(Major_Version, Minor_Version)
; Major_Version = 0, 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 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 <=
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:
To launch embedded mode:
swipl mqi --write_connection_values=true
This will start SWI Prolog and invoke the mqi_start/0
predicate and exit the process when that predicate stops. Any command
line arguments after the standalone -- will be passed as
Options. These are the same Options that mqi_start/1
accepts and are passed to it directly. Some options are expressed
differently due to command line limitations, see mqi_start/1
Options for more information.
Any Option values that cause issues during command line parsing (such
as spaces) should be passed with "" like this:
swipl mqi --write_connection_values=true --password="HGJ SOWLWW"
For help on commandline options run
swipl mqi --help
Always succeeds.