In case users see "lei-daemon" in ps(1) or syslog and wonder. --- Documentation/lei-daemon.pod | 61 ++++++++++++++++++++++++++++++ Documentation/lei.pod | 9 ++++- Documentation/lei_design_notes.txt | 2 +- MANIFEST | 1 + Makefile.PL | 2 +- 5 files changed, 72 insertions(+), 3 deletions(-) create mode 100644 Documentation/lei-daemon.pod
diff --git a/Documentation/lei-daemon.pod b/Documentation/lei-daemon.pod new file mode 100644 index 000000000000..1205e974706a --- /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<lei(1)> +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<fork(2)> new worker +processes to isolate and parallelize work. lei-daemon is +significantly more aggressive than read-only +L<public-inbox-daemon(8)> 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<lei(1)> and to internal workers. SOCK_SEQPACKET is guarantee +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 of changes and track keyword changes. + +The listen socket at (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<mailto:[email protected]> + +The mail archives are hosted at L<https://public-inbox.org/meta/> and +L<http://4uok3hntl7oi7b4uf4rtfwefqeexfzil2w6kgk2jn5z2f764irre7byd.onion/meta/> + +=head1 COPYRIGHT + +Copyright all contributors L<mailto:[email protected]> + +License: AGPL-3.0+ L<https://www.gnu.org/licenses/agpl-3.0.txt> + +=head1 SEE ALSO + +L<lei-overview(7)>, L<lei-daemon-kill(1)>, L<lei-daemon-pid(1)> diff --git a/Documentation/lei.pod b/Documentation/lei.pod index 3af9e2eeacf7..63d5ee6900a7 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<syslog(3)> as L<lei-daemon(8)> for the top-level daemon, +and C<lei/store> for the L<lei-store-format(5)> worker. + =head1 CONTACT Feedback welcome via plain-text mail to L<mailto:[email protected]> @@ -130,4 +137,4 @@ License: AGPL-3.0+ L<https://www.gnu.org/licenses/agpl-3.0.txt> =head1 SEE ALSO -L<lei-overview(7)> +L<lei-overview(7)>, L<lei-daemon(8)> diff --git a/Documentation/lei_design_notes.txt b/Documentation/lei_design_notes.txt index f1d2ab6f2169..b5180374ad05 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 diff --git a/MANIFEST b/MANIFEST index 3e942855127f..929f5f869c5b 100644 --- a/MANIFEST +++ b/MANIFEST @@ -27,6 +27,7 @@ Documentation/lei-config.pod Documentation/lei-convert.pod Documentation/lei-daemon-kill.pod Documentation/lei-daemon-pid.pod +Documentation/lei-daemon.pod Documentation/lei-edit-search.pod Documentation/lei-export-kw.pod Documentation/lei-forget-external.pod diff --git a/Makefile.PL b/Makefile.PL index 00a558d12472..c41c408a5704 100644 --- a/Makefile.PL +++ b/Makefile.PL @@ -60,7 +60,7 @@ $v->{-m5} = [ qw(public-inbox-config public-inbox-v1-format $v->{-m7} = [ qw(lei-overview lei-security public-inbox-overview public-inbox-tuning public-inbox-glossary) ]; -$v->{-m8} = [ qw(public-inbox-daemon) ]; +$v->{-m8} = [ qw(public-inbox-daemon lei-daemon) ]; my @sections = (1, 5, 7, 8); $v->{check_80} = []; $v->{manuals} = []; -- unsubscribe: one-click, see List-Unsubscribe header archive: https://public-inbox.org/meta/
