9a2d481fc3
Add a --listen option for the server Rework the option code to share the --listen / socket-path code between scm and server subcommands. Move option off the stack in mu.cc, seems it's too big, at least when using gdb.
97 lines
2.7 KiB
Org Mode
97 lines
2.7 KiB
Org Mode
#+TITLE: MU-SERVER
|
||
#+MAN_CLASS_OPTIONS: :section-id "@SECTION_ID@" :date "@MAN_DATE@"
|
||
#+include: macros.inc
|
||
|
||
* NAME
|
||
|
||
mu-server - the *mu* backend for the mu4e e-mail client
|
||
|
||
* SYNOPSIS
|
||
|
||
*mu* [_COMMON-OPTIONS_] *server*
|
||
|
||
* DESCRIPTION
|
||
|
||
*mu server* starts a simple shell in which one can query and manipulate the *mu*
|
||
database. The output uses s-expressions. *mu server* is not meant for use by
|
||
humans, except for debugging purposes. Instead, it is designed specifically for
|
||
the *mu4e* e-mail client.
|
||
|
||
#+begin_example
|
||
(<command-name> :param1 value1 :param2 value2)
|
||
#+end_example
|
||
|
||
For example, to view a certain message, the command would be:
|
||
|
||
#+begin_example
|
||
(view :docid 12345)
|
||
#+end_example
|
||
|
||
Parameters can be sent in any order; they must be of the correct type though.
|
||
See *lib/utils/mu-sexp-parser.hh* and *lib/utils/mu-sexp-parser.cc* in source-tree
|
||
for the details.
|
||
|
||
* OUTPUT FORMAT
|
||
|
||
*mu server* accepts a number of commands, and delivers its results in the form:
|
||
|
||
#+begin_example
|
||
\\376<length>\\377<s-expr>
|
||
#+end_example
|
||
|
||
\\376 (one byte 0xfe), followed by the length of the s-expression expressed as
|
||
an hexadecimal number, followed by another \\377 (one byte 0xff), followed by
|
||
the actual s-expression.
|
||
|
||
By prefixing the expression with its length, it can be processed more
|
||
efficiently. The \\376 and \\377 were chosen since they never occur in valid
|
||
UTF-8 (in which the s-expressions are encoded).
|
||
|
||
* SERVER OPTIONS
|
||
|
||
** --commands
|
||
List available commands (and try with *--verbose*).
|
||
|
||
** --eval _expression_
|
||
Evaluate a mu4e server s-expression.
|
||
|
||
** --allow-temp-file
|
||
If set, allow for the output of some commands to use temp-files rather than
|
||
directly through the emacs process input/output. This is noticeably faster for
|
||
commands with a lot of output, esp. when the the temp-file uses a in-memory
|
||
file-system.
|
||
|
||
** --listen
|
||
If set, the server starts an SCM REPL as well, which listens on a Unix domain
|
||
socket. This corresponds to the *--listen* options for *mu scm**.
|
||
|
||
The store object (including the Xapian database) is shared between the server and the REPL.
|
||
|
||
* PERFORMANCE
|
||
|
||
As an indication for the relative performance, we can simulate something ~mu4e~
|
||
does. We take the overall time of 50 such requests:
|
||
|
||
#+begin_src sh
|
||
time build/mu/mu server --allow-temp-file --eval '(find :query "\"\"" :include-related t :threads t :maxnum 50000)' >/dev/null
|
||
#+end_src
|
||
(and *--allow-temp-file* for 1.11)
|
||
|
||
#+ATTR_MAN: :disable-caption t
|
||
| release | time (sec) |
|
||
|---------------+------------|
|
||
| 1.8 | 8.6s |
|
||
| 1.10 | 5.7s |
|
||
| 1.11 (master) | 2.8s |
|
||
|
||
#+include: "muhome.inc" :minlevel 2
|
||
|
||
#+include: "common-options.inc" :minlevel 1
|
||
|
||
#+include: "prefooter.inc" :minlevel 1
|
||
|
||
* SEE ALSO
|
||
|
||
{{{man-link(mu,1)}}},
|
||
{{{man-link(mu-scm,1)}}}
|