diff options
Diffstat (limited to 'README')
| -rw-r--r-- | README | 101 |
1 files changed, 53 insertions, 48 deletions
@@ -1,92 +1,97 @@ -Devel::Mwrap - LD_PRELOAD malloc wrapper + malloc line stats for Perl += mwrap - LD_PRELOAD malloc wrapper + line stats for Ruby -Devel::Mwrap is designed to answer the question: +mwrap is designed to answer the question: - Which lines of Perl are hitting malloc the most? + Which lines of Ruby 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 -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. +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% +increase memory and runtime. -It is thread-safe and requires the concurrent lock-free hash table -from the Userspace RCU project: https://liburcu.org/ +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 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 requires the concurrent lock-free hash table from the +Userspace RCU project: https://liburcu.org/ -Tested on the `perl' package distributed with: +It does not require recompiling or rebuilding Ruby, but only +supports Ruby 2.7.0 or later on a few platforms: -* Debian GNU/Linux 10 and 11 - -* FreeBSD 12.x +* GNU/Linux +* FreeBSD It may work on NetBSD, OpenBSD and DragonFly BSD. == Install -See `INSTALL' document + # FreeBSD: pkg install liburcu + + # Debian-based systems: apt-get liburcu-dev + + # Install mwrap via RubyGems.org + gem install mwrap == Usage -Devel::Mwrap works as an LD_PRELOAD and supplies a mwrap-perl script to +mwrap works as an LD_PRELOAD and supplies a mwrap RubyGem executable 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-perl PERL_COMMAND + MWRAP=dump_path:/path/to/log mwrap RUBY_COMMAND # And to display the locations with the most allocations: sort -k1,1rn </path/to/log | $PAGER -You may also `use Devel::Mwrap' in your Perl code and use -Devel::Mwrap->dump, Devel::Mwrap->reset, Devel::Mwrap->each, etc. +You may also `require "mwrap"' in your Ruby code and use +Mwrap.dump, Mwrap.reset, Mwrap.each, etc. -However, Devel::Mwrap MUST be loaded via LD_PRELOAD to have any +However, mwrap MUST be loaded via LD_PRELOAD to have any effect in tracking malloc use. However, it is safe to keep -"use Devel::Mwrap" in performance-critical deployments, +"require 'mwrap'" in performance-critical deployments, as overhead is only incurred when used as an LD_PRELOAD. -The output of the Devel::Mwrap->dump is a text file with 3 columns: +The output of the mwrap dump is a text file with 3 columns: total_bytes call_count location -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. +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. -== Known problems +mwrap 2.0.0+ also supports a Rack application endpoint, +it is documented at: -* 32-bit machines are prone to overflow (WONTFIX) +https://80x24.org/mwrap/MwrapRack.html -* signalfd(2)-reliant code will need latest URCU with commit - ea3a28a3f71dd02f (Disable signals in URCU background threads, 2022-09-23) +== Known problems -* Perl source files over 16.7 million lines long are not supported :P +* 32-bit machines are prone to overflow (WONTFIX) -== Public mail archives (HTTP, Atom feeds, IMAP mailbox, NNTP group): +== Public mail archives and contact info: - https://80x24.org/mwrap-perl/ - imaps://80x24.org/inbox.comp.lang.perl.mwrap.0 - nntps://80x24.org/inbox.comp.lang.perl.mwrap +* 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 -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 will ever be required to post, but HTML mail +will be rejected: - mwrap-perl@80x24.org + mwrap-public@80x24.org == Hacking - git clone https://80x24.org/mwrap-perl.git + git clone https://80x24.org/mwrap.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. +Send all patches and pull requests (use "git request-pull" to format) to +mwrap-public@80x24.org. We do not use centralized or proprietary messaging +systems. == License |