diff options
Diffstat (limited to 'README')
| -rw-r--r-- | README | 42 |
1 files changed, 27 insertions, 15 deletions
@@ -1,21 +1,28 @@ = mwrap - LD_PRELOAD malloc wrapper + line stats for Ruby -Wraps all malloc, calloc, and realloc calls to trace the Ruby source -location of such calls and bytes allocated at each callsite. This -functionality may change incompatibly or be expanded in the future. +mwrap is designed to answer the question: -This is useful for finding malloc hotspots in Ruby code. It -does not track allocation lifetimes, or frees, however. It -works best for allocations under GVL, but tries to track numeric -caller addresses for allocations made without GVL. + Which lines of Ruby are hitting malloc the most? -It requires a concurrent lock-free hash table from the +mwrap wraps all malloc, calloc, and realloc calls to trace the Ruby +source location of such calls and bytes allocated at each callsite. +This functionality may be expanded in the future. + +It does not track allocation lifetimes, or frees, however. 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 requires the concurrent lock-free hash table from the Userspace RCU project: https://liburcu.org/ -Only supports Ruby trunk (2.6.0dev+) on a few platforms: +It does not require recompiling or rebuilding Ruby, but only supports +Ruby trunk (2.6.0dev+) on a few platforms: * GNU/Linux -* FreeBSD 11 +* FreeBSD (tested 11.1) + +It may work on NetBSD, OpenBSD and DragonFly BSD. == Install @@ -40,10 +47,17 @@ You may also set dump_path to append to a log file: MWRAP=dump_path:/path/to/log mwrap RUBY_COMMAND You may also `require 'mwrap'' in your Ruby code and use -Mwrap.dump, Mwrap.clear, Mwrap.each, etc. +Mwrap.dump, Mwrap.clear, Mwrap.reset, Mwrap.each, etc. + +However, mwrap MUST be loaded via LD_PRELOAD to have any +effect in tracking malloc use. -However, mwrap MUST be loaded via LD_PRELOAD-ed to have any -effect in tracking mallocs. +The output of the 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) == Known problems @@ -70,5 +84,3 @@ systems. == License GPL-2.0+ <https://www.gnu.org/licenses/gpl-2.0.txt> - -Note: we may depend on 3rd-party LGPL/GPL libraries in future releases |