documentation updates

Document the HTTP POST API and update the README with POP3
info and some minor rewording.  We'll also consistently use
`DIR' instead of `DIRECTORY' since it's shorter and well
understood (`opendir', `readdir', etc.)

3 files changed, 67 insertions, 16 deletions

diff --git a/README b/README
index f8a1d1b..1fa1dfb 100644
--- a/README
+++ b/README
@@ -66,16 +66,17 @@ malloc locations.
 
 * Perl source files over 16.7 million lines long are not supported :P
 
-== Public mail archives (HTTP, Atom feeds, IMAP mailbox, NNTP group):
+== Public mail archives (HTTP, Atom feeds, IMAP mailbox, NNTP group, POP3):
 
         https://80x24.org/mwrap-perl/
-        imaps://80x24.org/inbox.comp.lang.perl.mwrap.0
+        imaps://;AUTH=ANONYMOUS@80x24.org/inbox.comp.lang.perl.mwrap.0
         nntps://80x24.org/inbox.comp.lang.perl.mwrap
+        https://80x24.org/mwrap-perl/_/text/help/#pop3
 
-No subscription nor real identities will ever be required to
-obtain support.  Memory usage reductions start with you; only send
-plain-text mail to us and do not top-post.  HTML mail and top-posting
-costs everybody memory and bandwidth.
+No subscription nor real identities will ever be required to obtain support,
+but HTML mail is rejected.  Memory usage reductions start with you;
+only send plain-text mail to us and do not top-post.  HTML mail and
+top-posting costs everybody memory and bandwidth.
 
                 mwrap-perl@80x24.org
 
diff --git a/script/mwrap-perl b/script/mwrap-perl
index 82629b4..48f5471 100644
--- a/script/mwrap-perl
+++ b/script/mwrap-perl
@@ -28,8 +28,8 @@ mwrap-perl - run any command under mwrap
 
 =head1 SYNOPSIS
 
-  # to trace a long-running program and access it via $DIRECTORY/$PID.sock:
-  MWRAP=socket_dir:$DIRECTORY mwrap-perl COMMAND
+  # to trace a long-running program and access it via $DIR/$PID.sock:
+  MWRAP=socket_dir:$DIR mwrap-perl COMMAND
 
   # to trace a short-lived command and dump its output to a log:
   MWRAP=dump_path:$FILENAME mwrap-perl COMMAND
@@ -46,14 +46,16 @@ of native (C/C++) functions for non-Perl programs.
 C<MWRAP> is the only environment variable read.  It contains multiple
 options delimited by C<,> with names and values delimited by C<:>
 
-=item socket_dir:$DIRECTORY
+=over 4
+
+=item socket_dir:$DIR
 
 This launches an embedded HTTP server in each process and binds it
-to C<$DIRECTORY/$PID.sock>.  C<curl --unix-socket $DIRECTORY/$PID.sock>
+to C<$DIR/$PID.sock>.  C<curl --unix-socket $DIR/$PID.sock http://0/$PID/>
 or L<mwrap-rproxy(1p)> may be used to access various endpoints in
 the HTTP server.
 
-=item: bt:$DEPTH
+=item bt:$DEPTH
 
 The backtrace depth for L<backtrace(3)> in addition to the Perl
 file and line number where C<$DEPTH> is a non-negative number.
@@ -64,15 +66,63 @@ increase the amount of memory mwrap (and liburcu) itself uses.
 
 This is only useful in conjunction with C<socket_dir>
 
+This may be changed via POST request (see below).
+
 Default: 0
 
 =item dump_path:$FILENAME
 
-Dumps the output
+Dumps the output at exit to a given filename:
 
         total_bytes        call_count        location
 
-In the future, dumping to a self-describing CSV will be supported
+In the future, dumping to a self-describing CSV will be supported.
+
+=item dump_fd:$DESCRIPTOR
+
+As with dump_path, but dumps the output to a given file descriptor.
+
+=back
+
+=head1 HTTP POST API
+
+In addition to the various GET endpoints linked via C<http://0/$PID/>,
+there are some POST endpoints which are typically accessed via
+C<curl --unix-socket $DIR/$PID.sock>
+
+=over 4
+
+=item POST http://0/$PID/reset
+
+C<curl --unix-socket $DIR/$PID.sock -XPOST http://0/$PID/reset>
+
+Reset all internal counters.  This is not done atomically and does
+not release any memory.
+
+=item POST http://0/$PID/trim
+
+C<curl --unix-socket $DIR/$PID.sock -XPOST http://0/$PID/trim>
+
+Runs L<malloc_trim(3)> with a 0 pad value to release unused memory
+back to the kernel.  In our malloc implementation, this is done
+lazily to avoid contention and does not happen unless sleeping threads.
+
+=item POST http://0/$PID/ctl
+
+Set various internal knobs.  Currently, C<X-Mwrap-BT-Depth> is the
+only knob supported:
+
+C<curl --unix-socket $DIR/$PID.sock -XPOST -HX-Mwrap-BT-Depth:1 http://0/$PID/ctl>
+
+Using the C<X-Mwrap-BT-Depth> header allows changing the aforementioned
+C<bt:> value to a specified depth level.  As with C<bt:>, only make small
+adjustments as the memory cost can increase exponentially with each step.
+
+It is typically a good idea to reset (C<http://0/$PID/reset>) after changing
+the depth on a running process.
+
+Headers other than C<X-Mwrap-BT-Depth> may be accepted in the future to
+tweak other settings.
 
 =back
 
diff --git a/script/mwrap-rproxy b/script/mwrap-rproxy
index 2498bc3..056e80a 100644
--- a/script/mwrap-rproxy
+++ b/script/mwrap-rproxy
@@ -48,10 +48,10 @@ mwrap-rproxy - reverse proxy for embedded per-process mwrap httpd
 =head1 SYNOPSIS
 
   # start the long-running COMMAND you wish to trace:
-  MWRAP=socket_dir:$DIRECTORY mwrap-perl COMMAND
+  MWRAP=socket_dir:$DIR mwrap-perl COMMAND
 
   # in a different terminal, point mwrap-proxy to the mwrap-perl socket_dir
-  mwrap-rproxy --socket-dir=$DIRECTORY -l 127.0.0.1:8080
+  mwrap-rproxy --socket-dir=$DIR -l 127.0.0.1:8080
 
   # open http://127.0.0.1:8080/ in your favorite web browser:
   w3m http://127.0.0.1:8080/
@@ -71,7 +71,7 @@ traced by mwrap-perl.
 
 =over 4
 
-=item --socket-dir=DIRECTORY
+=item --socket-dir=DIR
 
 If unset, it will attempt to parse C<socket_dir:> from the C<MWRAP>
 environment (see L<mwrap-perl(1p)>).