mwrap-perl.git  about / heads / tags
LD_PRELOAD malloc wrapper + line stats for Perl
$ git log --pretty=format:'%h %s (%cs)%d'
6b67297 README: link to Ruby version, too (2024-01-09)
	(HEAD -> master)
7200d0e location_name: fix uninitialized variable warnings (2023-05-06)
1c99226 allow mremap and MAP_ANONYMOUS for large allocations (2023-02-22)
2d31f30 mymalloc: use file-backed DIRECT_MMAP, too (2023-02-01)
73d7e6d use perror(3) instead of fprintf(3) (2023-01-13)
bca8045 script/*: shorten and point to docs (2023-01-13)
0295f1f move _GNU_SOURCE definition (2023-01-13)
223134c mwrap-perl: update manpage to synopsis to favor CSV (2023-01-13)
3d09a04 fix uninitialized warnings (2023-01-11)
20add37 rewrite README and update manpage to favor CSV (2023-01-11)
...

$ git cat-file blob HEAD:README
Devel::Mwrap - LD_PRELOAD malloc wrapper + malloc line stats for Perl

Devel::Mwrap is designed to answer the question:

   Which lines of Perl are hitting malloc the most?

Devel::Mwrap wraps all malloc-family calls to trace the Perl
source location of such calls and bytes allocated at each
callsite.  It is primarily designed to identify high memory use,
but may function as a leak detector as it can show live
allocations at every call site.  Depending on your application
and workload, the overhead is roughly a 50%-100% increase memory
and runtime.

It also gives configurable backtraces of all dynamically-linked
malloc callsites for any program where backtrace(3) works,
including programs not linked to Perl.

It is thread-safe and requires the concurrent lock-free hash table
from the Userspace RCU project: https://liburcu.org/

It relies on dynamic linking to a malloc(3) implementation.  If
you got Perl from your OS distribution, this typically does not
require rebuilding Perl.

Tested on the `perl' package distributed with:

* Debian GNU/Linux 10 and 11

* FreeBSD 12.x

It may work on NetBSD, OpenBSD and DragonFly BSD.

== Install

See `INSTALL' document

== Usage

Devel::Mwrap works as an LD_PRELOAD and supplies a mwrap-perl wrapper to
improve ease-of-use.  You can set dump_csv: in the MWRAP environment
variable to append the results to a CSV file:

	MWRAP=dump_csv:/path/to/csv.%p mwrap-perl COMMAND

For long running processes, you can see the AF_UNIX HTTP interface:

	MWRAP=socket_dir:/some/dir mwrap-perl COMMAND

And connect via `curl --unix-socket /some/dir/$PID.sock' or `mwrap-rproxy'.
See mwrap-rproxy(1p) and mwrap-perl(1p) manpages for more info.

== Compared to other tools

* mwrap-perl knows about Perl code, and an `mwrap' RubyGem exists, too:
  https://80x24.org/mwrap.git

* mwrap does not catch memory errors; use ASan, valgrind, or similar

* mwrap is reasonably fast, fast enough for the author to run on
  production-facing Perl daemons

* the AF_UNIX HTTP interface allows inspecting live processes without
  interruption instead of waiting for an exit dump

== Known problems

* 32-bit machines are prone to overflow (WONTFIX)

* signalfd(2)-reliant code will need latest URCU with commit
  ea3a28a3f71dd02f (Disable signals in URCU background threads, 2022-09-23)

* Perl source files over 16.7 million lines long are not supported :P

* large C backtraces (off by default) are expensive for large programs

== Public mail archives (HTTP, Atom feeds, IMAP mailbox, NNTP group, POP3):

	https://80x24.org/mwrap-perl/
	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 or contribute, 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

== Hacking

	git clone https://80x24.org/mwrap-perl.git

Send all patches ("git format-patch" + "git send-email") and
pull requests (use "git request-pull" to format) via email
to mwrap-perl@80x24.org.  We do not and will not use
proprietary messaging systems.

== License

GPL-3.0+ <https://www.gnu.org/licenses/gpl-3.0.txt>

# heads (aka `branches'):
$ git for-each-ref --sort=-creatordate refs/heads \
	--format='%(HEAD) %(refname:short) %(subject) (%(creatordate:short))'
* master       README: link to Ruby version, too (2024-01-09)

# tags:
$ git for-each-ref --sort=-creatordate refs/tags \
	--format='%(refname:short) %(subject) (%(creatordate:short))'
# no tags, yet...

# associated public inboxes:
# (number on the left is used for dev purposes)
            https://80x24.org/mwrap-perl

git clone https://80x24.org/mwrap-perl.git