with_resources 0.1.0
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +7 -0
- data/.gitignore +9 -0
- data/Gemfile +4 -0
- data/LICENSE.txt +7 -0
- data/README.md +99 -0
- data/Rakefile +11 -0
- data/bin/console +14 -0
- data/bin/setup +8 -0
- data/lib/with_resources.rb +71 -0
- data/lib/with_resources/kernel_ext.rb +7 -0
- data/lib/with_resources/toplevel.rb +9 -0
- data/lib/with_resources/version.rb +3 -0
- data/misc/bench.rb +37 -0
- data/with_resources.gemspec +26 -0
- metadata +100 -0
checksums.yaml
ADDED
@@ -0,0 +1,7 @@
|
|
1
|
+
---
|
2
|
+
SHA1:
|
3
|
+
metadata.gz: 2b79f87e6ba35615184c783feba8e563a5302c73
|
4
|
+
data.tar.gz: 952d7783252f8b56c9d3d64e2c09a4fe42ba4ded
|
5
|
+
SHA512:
|
6
|
+
metadata.gz: a172db7c0cc1745e8827e7c4266555083381c16768350619847f50528438d1d280de472688b39d79ef2ba044f04fb75e0eebbf17c37f18a51fd04b500ba07c6a
|
7
|
+
data.tar.gz: 9983858d0bdd1723d055b676e1ce22ba77d2d229154eb9963488926b90cdaa6c5fdee5b4152fc14e6f7279371ddecfe116e20807a3a01edbe81beceee93cf042
|
data/.gitignore
ADDED
data/Gemfile
ADDED
data/LICENSE.txt
ADDED
@@ -0,0 +1,7 @@
|
|
1
|
+
Copyright 2017- Satoshi Tagomori
|
2
|
+
|
3
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
|
4
|
+
|
5
|
+
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
|
6
|
+
|
7
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
data/README.md
ADDED
@@ -0,0 +1,99 @@
|
|
1
|
+
# with_resources: Add "with" statement in your Ruby script
|
2
|
+
|
3
|
+
```ruby
|
4
|
+
# gem install with_resources
|
5
|
+
|
6
|
+
require "with_resources"
|
7
|
+
|
8
|
+
WithResourecs.with(->(){
|
9
|
+
sock = TCPSocket.open("dest.example.com", port)
|
10
|
+
httpclient = MyHTTPClient.new(sock)
|
11
|
+
}) do |sock, httpclient|
|
12
|
+
# ...
|
13
|
+
# httpclient.close # will be called automatically
|
14
|
+
# sock.close
|
15
|
+
end
|
16
|
+
|
17
|
+
require "with_resources/toplevel"
|
18
|
+
|
19
|
+
using WithResources::TopLevel
|
20
|
+
# it makes "with" available in this file
|
21
|
+
|
22
|
+
with(->(){ a = One.new; b = Another.new(a) }) do |a, b|
|
23
|
+
# ...
|
24
|
+
end
|
25
|
+
|
26
|
+
# or enable everywhere! (DANGER!)
|
27
|
+
require "with_resources/kernel_ext"
|
28
|
+
```
|
29
|
+
|
30
|
+
This gem provides a feature to allocate/release resource objects safely.
|
31
|
+
This feature is widely known as 'try-with-resources' (Java), 'with' statement (Python), 'using' statement (C#) and many others.
|
32
|
+
|
33
|
+
`WithResources.with` method does:
|
34
|
+
|
35
|
+
* accept a lambda argument to allocate resources
|
36
|
+
* accept a block to be called
|
37
|
+
* release allocated resources automatically after block is processed in reverse order of allocated order
|
38
|
+
|
39
|
+
All allocated resources will be released even when any errors are raised in block, in `obj.close` or in allocating another resources.
|
40
|
+
|
41
|
+
### Disclosure
|
42
|
+
|
43
|
+
This library is a kind of PoC to introduce safe resource allocation in Ruby world. Take care about using this library in your production environment.
|
44
|
+
|
45
|
+
## API
|
46
|
+
|
47
|
+
* `WithResources.with(lambda_to_allocate, release_method: :close, &block)`
|
48
|
+
|
49
|
+
All values assigned into local variable in `lambda_to_allocate` will be passed to `block` as block arguments. (Don't re-assign values into same local variable, neither undefine local variable, in that labmda.)
|
50
|
+
|
51
|
+
It can accept `release_method` keyword argument to specify the method name to release resources. The specified method will be called in release stage, without any arguments. It's impossible to specify different method names for resources.
|
52
|
+
|
53
|
+
### Introduce `with` to top-level namespace
|
54
|
+
|
55
|
+
Top level `with` is available via 2 different ways. One is using Refinements, another is modifying `Kernel` in open-class way.
|
56
|
+
|
57
|
+
```ruby
|
58
|
+
require "with_resources/toplevel"
|
59
|
+
using WithResources::TopLevel
|
60
|
+
|
61
|
+
with(->(){ r = create_resource() }) do |r|
|
62
|
+
# ...
|
63
|
+
end
|
64
|
+
```
|
65
|
+
|
66
|
+
Refinements is a feature of Ruby to apply Module modification in just a file (by `using` statement).
|
67
|
+
`using WithResources::TopLevel` introduces top level `with` in safer way than modifying `Kernel`.
|
68
|
+
|
69
|
+
```ruby
|
70
|
+
require "with_resource/kernel_ext"
|
71
|
+
|
72
|
+
# now, "with" is available everywhere...
|
73
|
+
```
|
74
|
+
|
75
|
+
Requiring `with_resource/kernel_ext` modifies `Kernel` module globally to add `with`. It's not recommended in most cases.
|
76
|
+
|
77
|
+
## Performance
|
78
|
+
|
79
|
+
Because of some magical hacks, `with` has performance overhead.
|
80
|
+
|
81
|
+
The benchmark score below shows the difference of performances between standard `begin-ensure` and `with` (elasped seconds by 10,000 times). Benchmark script is available at `misc/bench.rb`.
|
82
|
+
|
83
|
+
```
|
84
|
+
user system total real
|
85
|
+
begin 0.040000 0.000000 0.040000 ( 0.037753)
|
86
|
+
with 1.400000 0.010000 1.410000 ( 1.423388)
|
87
|
+
```
|
88
|
+
|
89
|
+
It's not so huge overhead in actual application, but it might be better to use `with` in heavy loops.
|
90
|
+
|
91
|
+
* * * * *
|
92
|
+
|
93
|
+
## Authors
|
94
|
+
|
95
|
+
* Satoshi Tagomori <tagomoris@gmail.com>
|
96
|
+
|
97
|
+
## License
|
98
|
+
|
99
|
+
MIT (See License.txt)
|
data/Rakefile
ADDED
data/bin/console
ADDED
@@ -0,0 +1,14 @@
|
|
1
|
+
#!/usr/bin/env ruby
|
2
|
+
|
3
|
+
require "bundler/setup"
|
4
|
+
require "with_resources"
|
5
|
+
|
6
|
+
# You can add fixtures and/or initialization code here to make experimenting
|
7
|
+
# with your gem easier. You can also use a different console, if you like.
|
8
|
+
|
9
|
+
# (If you use this, don't forget to add pry to your Gemfile!)
|
10
|
+
# require "pry"
|
11
|
+
# Pry.start
|
12
|
+
|
13
|
+
require "irb"
|
14
|
+
IRB.start(__FILE__)
|
data/bin/setup
ADDED
@@ -0,0 +1,71 @@
|
|
1
|
+
require "with_resources/version"
|
2
|
+
|
3
|
+
module WithResources
|
4
|
+
module ErrorExt
|
5
|
+
def suppressed
|
6
|
+
@suppressed ||= []
|
7
|
+
end
|
8
|
+
end
|
9
|
+
|
10
|
+
def self.with(allocation, release_method: :close, &block)
|
11
|
+
var_names = []
|
12
|
+
vars = {}
|
13
|
+
|
14
|
+
allocation_block_path = nil
|
15
|
+
allocation_block_lineno = nil
|
16
|
+
|
17
|
+
trace = TracePoint.new(:line, :b_return) do |tp|
|
18
|
+
if tp.event == :line && !tp.path.end_with?("lib/with_resources.rb") && allocation_block_path.nil?
|
19
|
+
allocation_block_path = tp.path
|
20
|
+
allocation_block_lineno = tp.lineno
|
21
|
+
end
|
22
|
+
if tp.event == :line && tp.path == allocation_block_path && tp.lineno >= allocation_block_lineno
|
23
|
+
tp_binding = tp.binding
|
24
|
+
tp_variables = tp_binding.local_variables
|
25
|
+
if var_names.all?{|resource_var| tp_variables.include?(resource_var) }
|
26
|
+
# hit! this block is resource allocation block
|
27
|
+
tp_variables.each do |name|
|
28
|
+
unless var_names.include?(name)
|
29
|
+
var_names << name
|
30
|
+
end
|
31
|
+
end
|
32
|
+
end
|
33
|
+
end
|
34
|
+
if tp.event == :b_return && tp.path == allocation_block_path && tp.lineno >= allocation_block_lineno
|
35
|
+
tp_binding = tp.binding
|
36
|
+
var_names.each do |name|
|
37
|
+
vars[name] = tp_binding.local_variable_get(name)
|
38
|
+
end
|
39
|
+
end
|
40
|
+
end
|
41
|
+
|
42
|
+
error = nil
|
43
|
+
return_value = nil
|
44
|
+
begin
|
45
|
+
trace.enable do
|
46
|
+
allocation.call
|
47
|
+
end
|
48
|
+
return_value = block.call(*vars.values)
|
49
|
+
rescue => e
|
50
|
+
error = e
|
51
|
+
error.extend(ErrorExt)
|
52
|
+
ensure
|
53
|
+
vars.values.reverse.each do |v|
|
54
|
+
if v.respond_to?(release_method)
|
55
|
+
begin
|
56
|
+
v.send(release_method)
|
57
|
+
rescue => e
|
58
|
+
if error
|
59
|
+
error.suppressed << e
|
60
|
+
else
|
61
|
+
error = e
|
62
|
+
error.extend(ErrorExt)
|
63
|
+
end
|
64
|
+
end
|
65
|
+
end
|
66
|
+
end
|
67
|
+
end
|
68
|
+
raise error if error
|
69
|
+
return_value
|
70
|
+
end
|
71
|
+
end
|
data/misc/bench.rb
ADDED
@@ -0,0 +1,37 @@
|
|
1
|
+
require "benchmark"
|
2
|
+
|
3
|
+
require "with_resources/toplevel"
|
4
|
+
using WithResources::TopLevel
|
5
|
+
|
6
|
+
n = 100_000
|
7
|
+
|
8
|
+
class Resource
|
9
|
+
def close
|
10
|
+
# do nothing
|
11
|
+
end
|
12
|
+
end
|
13
|
+
|
14
|
+
Benchmark.bm do |x|
|
15
|
+
x.report("begin") do
|
16
|
+
for i in 1..n
|
17
|
+
begin
|
18
|
+
a = Resource.new
|
19
|
+
begin
|
20
|
+
b = Resource.new
|
21
|
+
ensure
|
22
|
+
b.close
|
23
|
+
end
|
24
|
+
ensure
|
25
|
+
a.close
|
26
|
+
end
|
27
|
+
end
|
28
|
+
end
|
29
|
+
|
30
|
+
x.report("with") do
|
31
|
+
for i in 1..n
|
32
|
+
with(->(){ a = Resource.new; b = Resource.new }) do |a, b|
|
33
|
+
# nothing
|
34
|
+
end
|
35
|
+
end
|
36
|
+
end
|
37
|
+
end
|
@@ -0,0 +1,26 @@
|
|
1
|
+
# coding: utf-8
|
2
|
+
lib = File.expand_path('../lib', __FILE__)
|
3
|
+
$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
|
4
|
+
require 'with_resources/version'
|
5
|
+
|
6
|
+
Gem::Specification.new do |spec|
|
7
|
+
spec.name = "with_resources"
|
8
|
+
spec.version = WithResources::VERSION
|
9
|
+
spec.authors = ["TAGOMORI Satoshi"]
|
10
|
+
spec.email = ["tagomoris@gmail.com"]
|
11
|
+
|
12
|
+
spec.summary = %q{Introduce "with" statement.}
|
13
|
+
spec.description = %q{The library to provide "with" statement to allocate and release resources safely.}
|
14
|
+
spec.homepage = "https://github.com/tagomoris/with_resources"
|
15
|
+
spec.license = "MIT"
|
16
|
+
|
17
|
+
spec.files = `git ls-files -z`.split("\x0").reject do |f|
|
18
|
+
f.match(%r{^(test|spec|features)/})
|
19
|
+
end
|
20
|
+
spec.executables = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
|
21
|
+
spec.require_paths = ["lib"]
|
22
|
+
|
23
|
+
spec.add_development_dependency "bundler", "~> 1.14"
|
24
|
+
spec.add_development_dependency "rake", "~> 10.0"
|
25
|
+
spec.add_development_dependency "test-unit"
|
26
|
+
end
|
metadata
ADDED
@@ -0,0 +1,100 @@
|
|
1
|
+
--- !ruby/object:Gem::Specification
|
2
|
+
name: with_resources
|
3
|
+
version: !ruby/object:Gem::Version
|
4
|
+
version: 0.1.0
|
5
|
+
platform: ruby
|
6
|
+
authors:
|
7
|
+
- TAGOMORI Satoshi
|
8
|
+
autorequire:
|
9
|
+
bindir: bin
|
10
|
+
cert_chain: []
|
11
|
+
date: 2017-09-28 00:00:00.000000000 Z
|
12
|
+
dependencies:
|
13
|
+
- !ruby/object:Gem::Dependency
|
14
|
+
name: bundler
|
15
|
+
requirement: !ruby/object:Gem::Requirement
|
16
|
+
requirements:
|
17
|
+
- - "~>"
|
18
|
+
- !ruby/object:Gem::Version
|
19
|
+
version: '1.14'
|
20
|
+
type: :development
|
21
|
+
prerelease: false
|
22
|
+
version_requirements: !ruby/object:Gem::Requirement
|
23
|
+
requirements:
|
24
|
+
- - "~>"
|
25
|
+
- !ruby/object:Gem::Version
|
26
|
+
version: '1.14'
|
27
|
+
- !ruby/object:Gem::Dependency
|
28
|
+
name: rake
|
29
|
+
requirement: !ruby/object:Gem::Requirement
|
30
|
+
requirements:
|
31
|
+
- - "~>"
|
32
|
+
- !ruby/object:Gem::Version
|
33
|
+
version: '10.0'
|
34
|
+
type: :development
|
35
|
+
prerelease: false
|
36
|
+
version_requirements: !ruby/object:Gem::Requirement
|
37
|
+
requirements:
|
38
|
+
- - "~>"
|
39
|
+
- !ruby/object:Gem::Version
|
40
|
+
version: '10.0'
|
41
|
+
- !ruby/object:Gem::Dependency
|
42
|
+
name: test-unit
|
43
|
+
requirement: !ruby/object:Gem::Requirement
|
44
|
+
requirements:
|
45
|
+
- - ">="
|
46
|
+
- !ruby/object:Gem::Version
|
47
|
+
version: '0'
|
48
|
+
type: :development
|
49
|
+
prerelease: false
|
50
|
+
version_requirements: !ruby/object:Gem::Requirement
|
51
|
+
requirements:
|
52
|
+
- - ">="
|
53
|
+
- !ruby/object:Gem::Version
|
54
|
+
version: '0'
|
55
|
+
description: The library to provide "with" statement to allocate and release resources
|
56
|
+
safely.
|
57
|
+
email:
|
58
|
+
- tagomoris@gmail.com
|
59
|
+
executables: []
|
60
|
+
extensions: []
|
61
|
+
extra_rdoc_files: []
|
62
|
+
files:
|
63
|
+
- ".gitignore"
|
64
|
+
- Gemfile
|
65
|
+
- LICENSE.txt
|
66
|
+
- README.md
|
67
|
+
- Rakefile
|
68
|
+
- bin/console
|
69
|
+
- bin/setup
|
70
|
+
- lib/with_resources.rb
|
71
|
+
- lib/with_resources/kernel_ext.rb
|
72
|
+
- lib/with_resources/toplevel.rb
|
73
|
+
- lib/with_resources/version.rb
|
74
|
+
- misc/bench.rb
|
75
|
+
- with_resources.gemspec
|
76
|
+
homepage: https://github.com/tagomoris/with_resources
|
77
|
+
licenses:
|
78
|
+
- MIT
|
79
|
+
metadata: {}
|
80
|
+
post_install_message:
|
81
|
+
rdoc_options: []
|
82
|
+
require_paths:
|
83
|
+
- lib
|
84
|
+
required_ruby_version: !ruby/object:Gem::Requirement
|
85
|
+
requirements:
|
86
|
+
- - ">="
|
87
|
+
- !ruby/object:Gem::Version
|
88
|
+
version: '0'
|
89
|
+
required_rubygems_version: !ruby/object:Gem::Requirement
|
90
|
+
requirements:
|
91
|
+
- - ">="
|
92
|
+
- !ruby/object:Gem::Version
|
93
|
+
version: '0'
|
94
|
+
requirements: []
|
95
|
+
rubyforge_project:
|
96
|
+
rubygems_version: 2.6.13
|
97
|
+
signing_key:
|
98
|
+
specification_version: 4
|
99
|
+
summary: Introduce "with" statement.
|
100
|
+
test_files: []
|