diff options
Diffstat (limited to 'README')
| -rw-r--r-- | README | 86 |
1 files changed, 37 insertions, 49 deletions
@@ -1,71 +1,61 @@ -= mwrap - LD_PRELOAD malloc wrapper + line stats for Ruby +Devel::Mwrap - LD_PRELOAD malloc wrapper + malloc line stats for Perl -mwrap is designed to answer the question: +Devel::Mwrap is designed to answer the question: - Which lines of Ruby are hitting malloc the most? + Which lines of Perl are hitting malloc the most? -mwrap wraps all malloc-family calls to trace the Ruby source -location of such calls and bytes allocated at each callsite. -As of mwrap 2.0.0, it can also function as a leak detector -and show live allocations at every call site. Depending on -your application and workload, the overhead is roughly a 50-100% -increase memory and runtime with default settings. +Devel::Mwrap wraps all malloc-family calls to trace the Perl source +location of such calls and bytes allocated at each callsite. It +can also function as a leak detector and 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 works best for allocations under GVL, but tries to track -numeric caller addresses for allocations made without GVL so you -can get an idea of how much memory usage certain extensions and -native libraries use. +It is thread-safe and requires the concurrent lock-free hash table +from the Userspace RCU project: https://liburcu.org/ -It 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. -It does not require recompiling or rebuilding Ruby, but only -supports Ruby 2.7.0 or later on a few platforms: +Tested on the `perl' package distributed with: -* GNU/Linux (only tested --without-jemalloc, mwrap 3.x provides its own) +* Debian GNU/Linux 10 and 11 -It may work on FreeBSD, NetBSD, OpenBSD and DragonFly BSD if given -appropriate build options. +* FreeBSD 12.x -== Install +It may work on NetBSD, OpenBSD and DragonFly BSD. - # Debian-based systems: apt-get liburcu-dev +== Install - # Install mwrap via RubyGems.org - gem install mwrap +See `INSTALL' document == Usage -mwrap works as an LD_PRELOAD and supplies a mwrap RubyGem executable to +Devel::Mwrap works as an LD_PRELOAD and supplies a mwrap-perl script to improve ease-of-use. You can set dump_path: in the MWRAP environment variable to append the results to a log file: - MWRAP=dump_path:/path/to/log mwrap RUBY_COMMAND + MWRAP=dump_path:/path/to/log mwrap-perl PERL_COMMAND # And to display the locations with the most allocations: sort -k1,1rn </path/to/log | $PAGER -You may also `require "mwrap"' in your Ruby code and use -Mwrap.dump, Mwrap.reset, Mwrap.each, etc. +You may also `use Devel::Mwrap' in your Perl code and use +Devel::Mwrap->dump, Devel::Mwrap->reset, Devel::Mwrap->each, etc. -However, mwrap MUST be loaded via LD_PRELOAD to have any +However, Devel::Mwrap MUST be loaded via LD_PRELOAD to have any effect in tracking malloc use. However, it is safe to keep -"require 'mwrap'" in performance-critical deployments, +"use Devel::Mwrap" in performance-critical deployments, as overhead is only incurred when used as an LD_PRELOAD. -The output of the mwrap dump is a text file with 3 columns: +The output of the Devel::Mwrap->dump is a text file with 3 columns: total_bytes call_count location -Where location is a Ruby source location (if made under GVL) -or an address retrieved by backtrace_symbols(3). It is -recommended to use the sort(1) command on either of the -first two columns to find the hottest malloc locations. - -mwrap 3.0.0+ also supports an embedded HTTP server -it is documented at: - -https://80x24.org/mwrap.git/tree/Documentation/mwrap.pod +Where location is a Perl source location or an address retrieved +by backtrace_symbols(3). It is recommended to use the sort(1) +command on either of the first two columns to find the hottest +malloc locations. == Known problems @@ -73,28 +63,26 @@ https://80x24.org/mwrap.git/tree/Documentation/mwrap.pod * signalfd(2)-reliant code will need latest URCU with commit ea3a28a3f71dd02f (Disable signals in URCU background threads, 2022-09-23) - This doesn't affect C Ruby itself, and signalfd(2) use is rare - 3rd-party processes. -* Ruby source files over 16.7 million lines long are not supported :P +* Perl source files over 16.7 million lines long are not supported :P == Public mail archives (HTTP, Atom feeds, IMAP mailbox, NNTP group, POP3): -* https://80x24.org/mwrap-public/ -* nntps://80x24.org/inbox.comp.lang.ruby.mwrap -* imaps://;AUTH=ANONYMOUS@80x24.org/inbox.comp.lang.ruby.mwrap.0 -* https://80x24.org/mwrap-public/_/text/help/#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, 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-public@80x24.org + mwrap-perl@80x24.org == Hacking - git clone https://80x24.org/mwrap.git + 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 |