From e8a14610119b86133863182033c4b3e4df3f4257 Mon Sep 17 00:00:00 2001 From: Eric Wong Date: Mon, 9 Jan 2023 05:34:39 +0000 Subject: 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.) --- README | 13 ++++++----- script/mwrap-perl | 64 +++++++++++++++++++++++++++++++++++++++++++++++------ script/mwrap-rproxy | 6 ++--- 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 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 +to C<$DIR/$PID.sock>. C or L may be used to access various endpoints in the HTTP server. -=item: bt:$DEPTH +=item bt:$DEPTH The backtrace depth for L 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 +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, +there are some POST endpoints which are typically accessed via +C + +=over 4 + +=item POST http://0/$PID/reset + +C + +Reset all internal counters. This is not done atomically and does +not release any memory. + +=item POST http://0/$PID/trim + +C + +Runs L 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 is the +only knob supported: + +C + +Using the C header allows changing the aforementioned +C value to a specified depth level. As with C, only make small +adjustments as the memory cost can increase exponentially with each step. + +It is typically a good idea to reset (C) after changing +the depth on a running process. + +Headers other than C 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 from the C environment (see L). -- cgit v1.2.3-24-ge0c7