From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.2 (2018-09-13) on dcvr.yhbt.net X-Spam-Level: X-Spam-ASN: X-Spam-Status: No, score=-4.0 required=3.0 tests=ALL_TRUSTED,BAYES_00 shortcircuit=no autolearn=ham autolearn_force=no version=3.4.2 Received: from localhost (dcvr.yhbt.net [127.0.0.1]) by dcvr.yhbt.net (Postfix) with ESMTP id 83B801FC0D for ; Fri, 1 Oct 2021 09:54:46 +0000 (UTC) From: Eric Wong To: meta@public-inbox.org Subject: [PATCH 9/9] doc: lei-daemon: new manpage Date: Fri, 1 Oct 2021 09:54:45 +0000 Message-Id: <20211001095445.9326-10-e@80x24.org> In-Reply-To: <20211001095445.9326-1-e@80x24.org> References: <20211001095445.9326-1-e@80x24.org> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit List-Id: 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 +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 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 + +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 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 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 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} = [];