From: Eric Wong <e@80x24.org>
To: mwrap-perl@80x24.org
Subject: [PATCH 1/2] documentation updates
Date: Mon, 9 Jan 2023 05:34:39 +0000 [thread overview]
Message-ID: <20230109053440.2540892-2-e@80x24.org> (raw)
In-Reply-To: <20230109053440.2540892-1-e@80x24.org>
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<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)>).
next prev parent reply other threads:[~2023-01-09 5:34 UTC|newest]
Thread overview: 3+ messages / expand[flat|nested] mbox.gz Atom feed top
2023-01-09 5:34 [PATCH 0/2] doc and usability updates Eric Wong
2023-01-09 5:34 ` Eric Wong [this message]
2023-01-09 5:34 ` [PATCH 2/2] s/X-Mwrap-BT-Depth/X-Mwrap-BT/ Eric Wong
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20230109053440.2540892-2-e@80x24.org \
--to=e@80x24.org \
--cc=mwrap-perl@80x24.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://80x24.org/mwrap-perl.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).