From acb57675b5903778e2f740c624f04f7de4a7d0f0 Mon Sep 17 00:00:00 2001 From: Eshel Yaron Date: Fri, 22 Sep 2023 22:21:34 +0200 Subject: [PATCH] ; Improve documentation about shutting down Prolog * sweeprolog.el (sweeprolog-shutdown): Tweak and make interactive. * sweep.texi (Initialization): Document it, reorganize. --- sweep.texi | 106 +++++++++++++++++++++++++++++++------------------- sweeprolog.el | 22 +++++------ 2 files changed, 77 insertions(+), 51 deletions(-) diff --git a/sweep.texi b/sweep.texi index 173ae31..453638e 100644 --- a/sweep.texi +++ b/sweep.texi @@ -419,25 +419,10 @@ View the Sweep NEWS file. @chapter Prolog Initialization and Cleanup The embedded SWI-Prolog runtime must be initialized before it can -start executing queries. Initializing Prolog is usually taken care of -by Sweep when you first use a command that requires running some -Prolog code. This section elaborates about Prolog initialization and -its customization options in Sweep: - -@defun sweeprolog-initialize prog @r{@b{&rest}} args -Initialize the embedded Prolog runtime. @var{prog} should be the path -to the @command{swipl} executable, and @var{args} should be a list of -command line arguments for @command{swipl}. Sweep initializes Prolog -as if it was started from the command line as @code{@var{prog} -@var{args}}. -@end defun - -@defun sweeprolog-handle-command-line-args -Enable support for the Sweep specific @option{--swipl-args} Emacs -command line flag. This flag can be used to specify additional Prolog -initialization arguments for Sweep to use when initializing Prolog -on-demand, directly from Emacs's command line invocation. -@end defun +start executing queries. Normally, Sweep takes care of initializing +Prolog for you the first time you use a command that requires running +some Prolog code. This section elaborates about Prolog initialization +and its customization options in Sweep: @defopt sweeprolog-init-args List of strings used as initialization arguments for Prolog. Sweep @@ -445,19 +430,6 @@ uses these as the @var{args} argument of @code{sweeprolog-initialize} when it initializes Prolog on-demand. @end defopt -@findex sweeprolog-restart -@deffn Command sweeprolog-restart -Restart the embedded Prolog runtime. -@end deffn - -In Sweep, Prolog initialization is done via the C-implemented -@code{sweeprolog-initialize} Elisp function defined in -@code{sweep-module}. @code{sweeprolog-initialize} takes one or more -string arguments and initializes the embedded Prolog as if it were -invoked externally in a command line with the given strings as command -line arguments, where the first argument to -@code{sweeprolog-initialize} corresponds to @code{argv[0]}. - Sweep loads and initializes Prolog on-demand at the first invocation of a command that requires the embedded Prolog. The user option @code{sweeprolog-init-args} says which arguments to pass to Prolog @@ -471,6 +443,24 @@ your Emacs configuration: (push "--stack-limit=512m" sweeprolog-init-args)) @end lisp +Sweep initializes Prolog from Elisp by calling function +@code{sweeprolog-initialize}. + +@defun sweeprolog-initialize prog @r{@b{&rest}} args +Initialize the embedded Prolog runtime. @var{prog} should be the path +to the @command{swipl} executable, and @var{args} should be a list of +command line arguments for @command{swipl}. Sweep initializes Prolog +as if it was started from the command line as @code{@var{prog} +@var{args}}. +@end defun + +The function @code{sweeprolog-initialize} takes one or more string +arguments and initializes the embedded Prolog as if it were invoked +externally in a command line with the given strings as command line +arguments, where the first argument to @code{sweeprolog-initialize} +corresponds to @code{argv[0]}. This function is implemented in C in +@code{sweep-module} (@pxref{Architecture}). + @cindex sweep Prolog flag The default value of @code{sweeprolog-init-args} is set to load the Prolog helper library @file{sweep.pl} and to create a boolean Prolog @@ -496,20 +486,56 @@ emacs --some-emacs-option --swipl-args -l foobar.pl \; --more-emacs-options In order for Sweep to be able to handle Emacs's command line arguments, you must call @code{sweeprolog-handle-command-line-args} -before Emacs processes the @option{--swipl-args} argument. You can do -this, for example, by calling it from the command line right before +before Emacs processes the @option{--swipl-args} argument. + +@defun sweeprolog-handle-command-line-args +Enable support for the Sweep-specific @option{--swipl-args} Emacs +command line flag. This flag can be used to specify additional Prolog +initialization arguments for Sweep to use when initializing Prolog +on-demand, directly from Emacs's command line invocation. +@end defun + +This function makes Emacs recognize the @option{--swipl-args} command +line flag by adding a dedicated handler function to +@code{command-line-functions} (@pxref{Command-Line +Arguments,,,elisp,}). If you want to use @option{--swipl-args}, you +should arrange for @code{command-line-functions} to run before Emacs +processes @option{--swipl-args}. To do that, either place a call +@code{sweeprolog-handle-command-line-args} in your Emacs +configuration, or call it from the command line right before @option{--swipl-args}: @example emacs -f sweeprolog-handle-command-line-args --swipl-args -l foobar.pl \; @end example -You can reset the embedded Prolog runtime using the command -@code{sweeprolog-restart}. This command cleans up the the Prolog -state and resources, and starts it anew. When you call it with a -prefix argument (@kbd{C-u M-x sweeprolog-restart @key{RET}}), it prompts for -additional initialization arguments to pass to the embedded Prolog -runtime on startup. +@cindex restart Prolog +@cindex shutdown Prolog +@cindex cleanup Prolog +You can shut down or restart the embedded Prolog runtime using the +following commands: + +@findex sweeprolog-shutdown +@deffn Command sweeprolog-shutdown +Shut down the embedded Prolog runtime. +@end deffn + +@deffn Command sweeprolog-restart +Restart the embedded Prolog runtime. +@end deffn + +The command @code{sweeprolog-shutdown} shuts down the Prolog runtime +and frees up resources Prolog allocated. You cannot shut down Prolog +with running top-levels (@pxref{The Prolog Top-level})---if you invoke +@code{sweeprolog-shutdown} while you have running top-levels, this +command suggests killing them, and if you refuse it complains and +keeps Prolog running. The command @code{sweeprolog-restart} is +similar to @code{sweeprolog-shutdown}, expect it starts the embedded +Prolog runtime anew after shutting it down. When you invoke +@code{sweeprolog-restart} with a prefix argument (@kbd{C-u M-x +sweeprolog-restart @key{RET}}), this command prompts for additional +initialization arguments to pass to the embedded Prolog runtime when +restarting it. @node Querying Prolog @chapter Querying Prolog diff --git a/sweeprolog.el b/sweeprolog.el index 819a6e8..6ead965 100644 --- a/sweeprolog.el +++ b/sweeprolog.el @@ -707,7 +707,7 @@ extra initialization arguments." args)))) (setq sweeprolog--initialized t) (add-hook 'kill-emacs-query-functions #'sweeprolog-maybe-kill-top-levels) - (add-hook 'kill-emacs-hook #'sweeprolog-shutdown) + (add-hook 'kill-emacs-hook #'sweeprolog--shutdown) (sweeprolog-setup-message-hook))) (defun sweeprolog-maybe-kill-top-levels () @@ -726,7 +726,7 @@ extra initialization arguments." (dolist (buffer top-levels) (sweeprolog-top-level-delete-process buffer))))))) -(defun sweeprolog-shutdown () +(defun sweeprolog--shutdown () "Shutdown Prolog." (message "Stopping Sweep.") (sweeprolog--query-once "sweep" "sweep_cleanup_threads" nil) @@ -734,11 +734,12 @@ extra initialization arguments." (setq sweeprolog--initialized nil sweeprolog-prolog-server-port nil)) -(defun sweeprolog-maybe-shutdown () +(defun sweeprolog-shutdown () "Ask before killing running top-levels and shutdown Prolog." - (when (sweeprolog-maybe-kill-top-levels) - (sweeprolog-shutdown) - t)) + (interactive) + (if (sweeprolog-maybe-kill-top-levels) + (sweeprolog--shutdown) + (user-error "Cannot restart Sweep with running top-levels"))) (defun sweeprolog-restart (&rest args) "Restart the embedded Prolog runtime. @@ -754,11 +755,10 @@ Otherwise set ARGS to nil." current-prefix-arg (fboundp 'split-string-shell-command) (split-string-shell-command (read-string "swipl arguments: ")))) - (if (sweeprolog-maybe-shutdown) - (progn - (sit-for 1) - (apply #'sweeprolog-init args)) - (user-error "Cannot restart Sweep with running top-levels"))) + (sweeprolog-shutdown) + (progn + (sit-for 1) + (apply #'sweeprolog-init args))) (defun sweeprolog--open-query (ctx mod fun arg &optional rev) "Ensure that Prolog is initialized and execute a new query. -- 2.39.2