From a1d11ab624367884f3cff76c13aba85be3a89e45 Mon Sep 17 00:00:00 2001 From: Eric Wong Date: Fri, 1 Oct 2021 09:54:45 +0000 Subject: doc: lei-daemon: new manpage In case users see "lei-daemon" in ps(1) or syslog and wonder. Helped-by: Kyle Meyer --- Documentation/lei-daemon.pod | 61 ++++++++++++++++++++++++++++++++++++++ Documentation/lei.pod | 9 +++++- Documentation/lei_design_notes.txt | 2 +- 3 files changed, 70 insertions(+), 2 deletions(-) create mode 100644 Documentation/lei-daemon.pod (limited to 'Documentation') diff --git a/Documentation/lei-daemon.pod b/Documentation/lei-daemon.pod new file mode 100644 index 00000000..92bc9ac5 --- /dev/null +++ b/Documentation/lei-daemon.pod @@ -0,0 +1,61 @@ +=head1 NAME + +lei-daemon - technical information for local email interface daemon + +=head1 DESCRIPTION + +This documentation is a high-level overview for developers and +administrators interested in how lei works. + +lei-daemon is a background daemon which powers the L +command-line tool. It may support virtual users and read-write +IMAP+JMAP APIs in the future. It is designed to optimize shell +completion by avoiding module loading costs, monitor Maildirs +(and in the near future, IMAP folders) for changes. + +=head2 worker processes + +Most commands cause lei-daemon to L new worker +processes to isolate and parallelize work. lei-daemon is +significantly more aggressive than read-only +L processes with regards to resource use +since it's not designed to support C10K/C100K scenarios. + +=head2 file descriptor passing + +FD passing is used to reduce IPC costs for bulk I/O when +importing large mboxes from stdin and dumping large mboxes +to stdout. + +=head2 SOCK_SEQPACKET + +SOCK_SEQPACKET sockets are used for both communicating with +L and to internal workers. SOCK_SEQPACKET guarantees +reliability (unlike SOCK_DGRAM), allows easy load distribution, +and saves developers the trouble of maintaining stream parsers. + +=head2 file monitoring + +Inotify or EVFILT_VNODE is used depending on the platform +to monitor Maildirs for changes and track keyword changes. + +The listen socket (default: C<$XDG_RUNTIME_DIR/lei/5.seq.sock>) +is also monitored, and the daemon will automatically shutdown +if it is unlinked. + +=head1 CONTACT + +Feedback welcome via plain-text mail to L + +The mail archives are hosted at L and +L + +=head1 COPYRIGHT + +Copyright all contributors L + +License: AGPL-3.0+ L + +=head1 SEE ALSO + +L, L, L diff --git a/Documentation/lei.pod b/Documentation/lei.pod index 3af9e2ee..63d5ee69 100644 --- a/Documentation/lei.pod +++ b/Documentation/lei.pod @@ -115,6 +115,13 @@ Other subcommands include By default storage is located at C<$XDG_DATA_HOME/lei/store>. The configuration for lei resides at C<$XDG_CONFIG_HOME/lei/config>. +=head1 ERRORS + +Errors and dianostics for interactive commands are reported to +stderr. Some errors for background tasks are emitted via +L as L for the top-level daemon, +and C for the L worker. + =head1 CONTACT Feedback welcome via plain-text mail to L @@ -130,4 +137,4 @@ License: AGPL-3.0+ L =head1 SEE ALSO -L +L, L diff --git a/Documentation/lei_design_notes.txt b/Documentation/lei_design_notes.txt index f1d2ab6f..b5180374 100644 --- a/Documentation/lei_design_notes.txt +++ b/Documentation/lei_design_notes.txt @@ -6,7 +6,7 @@ Daemon architecture The use of a persistent daemon works around slow startup time of Perl. This is especially important for built-in support for -shell completion. It will eventually support inotify and EVFILT_VNODE +shell completion. It attempts to support inotify and EVFILT_VNODE background monitoring of Maildir keyword changes. If lei were reimplemented in a language with faster startup -- cgit v1.2.3-24-ge0c7