diff options
Diffstat (limited to 'Documentation')
| -rw-r--r-- | Documentation/lei-daemon.pod | 61 | ||||
| -rw-r--r-- | Documentation/lei.pod | 9 | ||||
| -rw-r--r-- | Documentation/lei_design_notes.txt | 2 |
3 files changed, 70 insertions, 2 deletions
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<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 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<mailto:meta@public-inbox.org> + +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:meta@public-inbox.org> + +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 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<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:meta@public-inbox.org> @@ -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 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 |