majo 0.0.3 → 0.0.4

Sign up to get free protection for your applications and to get access to all the features.
Files changed (10) hide show
  1. checksums.yaml +4 -4
  2. data/README.md +126 -8
  3. data/lib/majo/colorize.rb +11 -0
  4. data/lib/majo/formatter/color.rb +14 -2
  5. data/lib/majo/formatter/monochrome.rb +15 -0
  6. data/lib/majo/formatter.rb +1 -0
  7. data/lib/majo/result.rb +9 -1
  8. data/lib/majo/version.rb +1 -1
  9. data/lib/majo.rb +1 -0
  10. metadata +5 -3
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 30b12103910ff82b8073d3882debca86928bc05d03e318b8c640e0c3b6f4c6ee
4
- data.tar.gz: 851e43d87d7ba4020b5eb04487ae9859522bba5bd7f7a6765d02432efe2b8d74
3
+ metadata.gz: c68eebecd1591a5579a3c44135c7d29c7b46743c0f35c65f8ebd3b557bd78f4a
4
+ data.tar.gz: 5742f4feabbead870b4becbeb8c40f5591eff79541f3f70dd4aef285c1de5f0d
5
5
  SHA512:
6
- metadata.gz: ee86c8d4f321e54646ec82ee79168a8071ff641be47f9fd006ab70c9f254fbd958e6667c1e9dde36b00e911eee17d970a09a785dd53912f9bc4383101e649957
7
- data.tar.gz: 3b707eee86c906409bd26f9b15e0e35aa1e6516e566b7d0f7e526b4fc76d74478110f75aa77b23041133d8b966999882c46d60515617121d7eec9cd41d9c3ac1
6
+ metadata.gz: e1e165da4e081ca6886db4631f1052bab452551b073784c90507da80d1f35672edc0a9b7ead753b32c5d1fc7884e8fe87778c76b38c0b8dbadbde417362902db
7
+ data.tar.gz: 24cfe454a1f38b70f7c1b12d6f4bd3a1cf94384b9f18eabe10e27907e93c5b0e8417e53d405582086571e4cd649ca14d6d4cdd05e5e5b50794ff2994cc1f077f
data/README.md CHANGED
@@ -1,24 +1,142 @@
1
- # Majo
1
+ # Majo🧙‍♀️
2
2
 
3
- TODO: Delete this and the text below, and describe your gem
3
+ A memory profiler focusing on long-lived objects.
4
4
 
5
- Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/majo`. To experiment with that code, run `bin/console` for an interactive prompt.
5
+ ## Motivation
6
6
 
7
- ## Installation
7
+ I created this gem because I wanted to reduce the maximum memory usage of a Ruby program.
8
+
9
+ The existing memory profiler, `memory_profiler` gem, focuses on allocated and retained memory. This tool is useful to reduce allocations and retain memory, but it is not suitable for reducing the maximum memory usage.
8
10
 
9
- TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
11
+ This gem solves this problem by focusing on long-lived objects. Long-lived objects are objects that are not garbage collected for a long time. These objects are the main cause of the maximum memory usage.
12
+
13
+ ## Installation
10
14
 
11
15
  Install the gem and add to the application's Gemfile by executing:
12
16
 
13
- $ bundle add UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
17
+ $ bundle add majo --group development
14
18
 
15
19
  If bundler is not being used to manage dependencies, install the gem by executing:
16
20
 
17
- $ gem install UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
21
+ $ gem install majo
18
22
 
19
23
  ## Usage
20
24
 
21
- TODO: Write usage instructions here
25
+ Wrap the code you want to profile with `Majo.run`.
26
+ Then, call `report` method to display the result.
27
+
28
+ ```ruby
29
+ result = Majo.run do
30
+ code_to_profile
31
+ end
32
+
33
+ result.report
34
+ ```
35
+
36
+ ### Options
37
+
38
+ You can pass the following options to `report` method.
39
+
40
+ | Name | Description | Default | Type |
41
+ | ----------- | ------------------------ | --------- | ------------------------------------------------------------------------ |
42
+ | `out` | Output file or IO | `$stdout` | `IO`, `String` or an object having `to_path` method (such as `Pathname`) |
43
+ | `formatter` | The format of the result | `:color` | `:color`, or `:csv` |
44
+
45
+ For example:
46
+
47
+ ```ruby
48
+ result = Majo.run do
49
+ code_to_profile
50
+ end
51
+
52
+ result.report(out: "majo-result.csv", formatter: :csv)
53
+ ```
54
+
55
+ ### Result Example
56
+
57
+ The result contains only long-lived objects, which are collected by the major GC.
58
+
59
+ The example is as follows:
60
+
61
+ ```
62
+ Total 15055372 bytes (159976 objects)
63
+
64
+ Memory by file
65
+ -----------------------------------
66
+ 10431760 /path/to/gems/rbs-3.5.1/lib/rbs/parser_aux.rb
67
+ 1966348 /path/to/gems/rbs-3.5.1/lib/rbs/environment_loader.rb
68
+ 980344 /path/to/gems/rbs-3.5.1/lib/rbs/types.rb
69
+ (snip)
70
+
71
+ Memory by location
72
+ -----------------------------------
73
+ 10431760 /path/to/gems/rbs-3.5.1/lib/rbs/parser_aux.rb:20
74
+ 1942812 /path/to/gems/rbs-3.5.1/lib/rbs/environment_loader.rb:159
75
+ 249920 /path/to/gems/rbs-3.5.1/lib/rbs/types.rb:994
76
+ (snip)
77
+
78
+ Memory by class
79
+ -----------------------------------
80
+ 4274028 String
81
+ 3556632 RBS::Location
82
+ 2197840 Array
83
+ (snip)
84
+
85
+ Objects by file
86
+ -----------------------------------
87
+ 109126 /path/to/gems/rbs-3.5.1/lib/rbs/parser_aux.rb
88
+ 20813 /path/to/gems/rbs-3.5.1/lib/rbs/types.rb
89
+ 12236 /path/to/gems/rbs-3.5.1/lib/rbs/environment.rb
90
+ (snip)
91
+
92
+ Objects by location
93
+ -----------------------------------
94
+ 109126 /path/to/gems/rbs-3.5.1/lib/rbs/parser_aux.rb:20
95
+ 4458 /path/to/gems/rbs-3.5.1/lib/rbs/namespace.rb:24
96
+ 4132 /path/to/gems/rbs-3.5.1/lib/rbs/types.rb:374
97
+ (snip)
98
+
99
+ Objects by class
100
+ -----------------------------------
101
+ 52495 Array
102
+ 22435 RBS::Location
103
+ 11144 RBS::TypeName
104
+ (snip)
105
+ ```
106
+
107
+ The CSV format is as follows:
108
+
109
+ ```csv
110
+ Object class path,Class path,Method ID,Path,Line,Alloc generation,Free generation,Memsize,Count
111
+ Hash,,_parse_signature,/path/to/gems/rbs-3.5.1/lib/rbs/parser_aux.rb,20,20,22,160,3
112
+ Hash,RBS::EnvironmentLoader,each_signature,/path/to/gems/rbs-3.5.1/lib/rbs/environment_loader.rb,159,20,22,160,1
113
+ Hash,,_parse_signature,/path/to/gems/rbs-3.5.1/lib/rbs/parser_aux.rb,20,21,23,160,1
114
+ (snip)
115
+ ```
116
+
117
+ You can find the raw data in the CSV format. It is useful for further analysis. For example: [A spreadsheet for Majo result](https://docs.google.com/spreadsheets/d/1Qe6ZSJ58bNfLbA_eSuL9FJy89taNPt325qAJnLDorOE/edit?gid=533761210#gid=533761210)
118
+
119
+ The columns are as follows:
120
+
121
+ | Column name | Description |
122
+ | ------------------- | ------------------------------------------------------------------ |
123
+ | `Object class path` | The class name of the allocated object |
124
+ | `Class path` | The class name of the receiver of the method allocating the object |
125
+ | `Method ID` | The method name allocating the object |
126
+ | `Path` | The file path of the method allocating the object |
127
+ | `Line` | The line number of the method allocating the object |
128
+ | `Alloc generation` | The GC generation number when the object is allocated |
129
+ | `Free generation` | The GC generation number when the object is freed |
130
+ | `Memsize` | The memory size of the object in bytes |
131
+ | `Count` | Number of objects allocated with the same conditions |
132
+
133
+ ## Name
134
+
135
+ The name "Majo" is a Japanese word `魔女` that means "witch". It is a wordplay on the word "major" in "major GC".
136
+
137
+ ## Thanks
138
+
139
+ This gem is inspired by [memory_profiler](https://github.com/SamSaffron/memory_profiler) gem.
22
140
 
23
141
  ## Development
24
142
 
data/lib/majo/colorize.rb ADDED
@@ -0,0 +1,11 @@
1
+ module Majo
2
+ module Colorize
3
+ def blue(str)
4
+ "\e[34m#{str}\e[0m"
5
+ end
6
+
7
+ def cyan(str)
8
+ "\e[36m#{str}\e[0m"
9
+ end
10
+ end
11
+ end
data/lib/majo/formatter/color.rb CHANGED
@@ -1,6 +1,8 @@
1
1
  module Majo
2
2
  module Formatter
3
3
  class Color
4
+ include Colorize
5
+
4
6
  def initialize(result)
5
7
  @result = result
6
8
  end
@@ -10,21 +12,27 @@ module Majo
10
12
  Total #{total_memory} bytes (#{total_objects} objects)
11
13
 
12
14
  Memory by file
15
+ #{bar}
13
16
  #{format_two_columns(memory_by_file)}
14
17
 
15
18
  Memory by location
19
+ #{bar}
16
20
  #{format_two_columns(memory_by_location)}
17
21
 
18
22
  Memory by class
23
+ #{bar}
19
24
  #{format_two_columns(memory_by_class)}
20
25
 
21
26
  Objects by file
27
+ #{bar}
22
28
  #{format_two_columns(objects_by_file)}
23
29
 
24
30
  Objects by location
31
+ #{bar}
25
32
  #{format_two_columns(objects_by_location)}
26
33
 
27
34
  Objects by class
35
+ #{bar}
28
36
  #{format_two_columns(objects_by_class)}
29
37
  RESULT
30
38
  end
@@ -33,6 +41,10 @@ module Majo
33
41
 
34
42
  attr_reader :result
35
43
 
44
+ def bar
45
+ cyan '-----------------------------------'
46
+ end
47
+
36
48
  def total_objects
37
49
  allocs.size
38
50
  end
@@ -80,8 +92,8 @@ module Majo
80
92
  def format_two_columns(data)
81
93
  return "" if data.empty?
82
94
 
83
- max_length = data.max_by { |row| row[0].to_s.size }[0].size
84
- data.map { |row| "#{row[0].to_s.ljust(max_length)} #{row[1]}" }.join("\n")
95
+ max_length = data.max_by { |row| row[0].to_s.size }[0].to_s.size
96
+ data.map { |row| "#{blue(row[0].to_s.rjust(max_length))} #{row[1]}" }.join("\n")
85
97
  end
86
98
 
87
99
  def allocs
data/lib/majo/formatter/monochrome.rb ADDED
@@ -0,0 +1,15 @@
1
+ module Majo
2
+ module Formatter
3
+ class Monochrome < Color
4
+ private
5
+
6
+ def blue(str)
7
+ str
8
+ end
9
+
10
+ def cyan(str)
11
+ str
12
+ end
13
+ end
14
+ end
15
+ end
data/lib/majo/formatter.rb CHANGED
@@ -1,6 +1,7 @@
1
1
  module Majo
2
2
  module Formatter
3
3
  autoload :Color, 'majo/formatter/color'
4
+ autoload :Monochrome, 'majo/formatter/monochrome'
4
5
  autoload :CSV, 'majo/formatter/csv'
5
6
  end
6
7
  end
data/lib/majo/result.rb CHANGED
@@ -3,10 +3,18 @@ module Majo
3
3
  def report(out: $stdout, formatter: nil)
4
4
  fmt =
5
5
  case formatter
6
- when nil, :color
6
+ when :color
7
7
  Formatter::Color
8
8
  when :csv
9
9
  Formatter::CSV
10
+ when :monochrome
11
+ Formatter::Monochrome
12
+ when nil
13
+ if out.respond_to?(:tty?) && out.tty?
14
+ Formatter::Color
15
+ else
16
+ Formatter::Monochrome
17
+ end
10
18
  else
11
19
  raise "unknown formatter: #{formatter.inspect}"
12
20
  end
data/lib/majo/version.rb CHANGED
@@ -1,5 +1,5 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  module Majo
4
- VERSION = "0.0.3"
4
+ VERSION = "0.0.4"
5
5
  end
data/lib/majo.rb CHANGED
@@ -2,6 +2,7 @@
2
2
 
3
3
  require_relative 'majo.so'
4
4
  require_relative "majo/version"
5
+ require_relative "majo/colorize"
5
6
  require_relative 'majo/allocation_info'
6
7
  require_relative 'majo/result'
7
8
  require_relative 'majo/formatter'
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: majo
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.0.3
4
+ version: 0.0.4
5
5
  platform: ruby
6
6
  authors:
7
7
  - Masataka Pocke Kuwabara
@@ -9,7 +9,7 @@ bindir: exe
9
9
  cert_chain: []
10
10
  date: 2024-07-22 00:00:00.000000000 Z
11
11
  dependencies: []
12
- description: ''
12
+ description: A memory profiler focusing on long-lived objects.
13
13
  email:
14
14
  - kuwabara@pocke.me
15
15
  executables: []
@@ -34,9 +34,11 @@ files:
34
34
  - ext/majo/unique_str.h
35
35
  - lib/majo.rb
36
36
  - lib/majo/allocation_info.rb
37
+ - lib/majo/colorize.rb
37
38
  - lib/majo/formatter.rb
38
39
  - lib/majo/formatter/color.rb
39
40
  - lib/majo/formatter/csv.rb
41
+ - lib/majo/formatter/monochrome.rb
40
42
  - lib/majo/result.rb
41
43
  - lib/majo/version.rb
42
44
  - sig/majo.rbs
@@ -62,5 +64,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
62
64
  requirements: []
63
65
  rubygems_version: 3.6.0.dev
64
66
  specification_version: 4
65
- summary: ''
67
+ summary: A memory profiler focusing on long-lived objects.
66
68
  test_files: []