rbs 1.4.0 → 1.6.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/.github/dependabot.yml +10 -0
- data/CHANGELOG.md +52 -0
- data/Gemfile +2 -0
- data/Steepfile +9 -1
- data/core/builtin.rbs +1 -1
- data/core/file.rbs +3 -1
- data/core/global_variables.rbs +3 -3
- data/core/io/wait.rbs +37 -0
- data/core/io.rbs +6 -4
- data/core/ractor.rbs +779 -0
- data/core/string_io.rbs +3 -5
- data/docs/collection.md +116 -0
- data/lib/rbs/builtin_names.rb +1 -0
- data/lib/rbs/cli.rb +93 -2
- data/lib/rbs/collection/cleaner.rb +29 -0
- data/lib/rbs/collection/config/lockfile_generator.rb +95 -0
- data/lib/rbs/collection/config.rb +85 -0
- data/lib/rbs/collection/installer.rb +27 -0
- data/lib/rbs/collection/sources/git.rb +147 -0
- data/lib/rbs/collection/sources/rubygems.rb +40 -0
- data/lib/rbs/collection/sources/stdlib.rb +38 -0
- data/lib/rbs/collection/sources.rb +22 -0
- data/lib/rbs/collection.rb +13 -0
- data/lib/rbs/environment_loader.rb +12 -0
- data/lib/rbs/errors.rb +2 -0
- data/lib/rbs/repository.rb +13 -7
- data/lib/rbs/validator.rb +4 -1
- data/lib/rbs/version.rb +1 -1
- data/lib/rbs.rb +1 -0
- data/sig/builtin_names.rbs +1 -0
- data/sig/cli.rbs +5 -0
- data/sig/collection/cleaner.rbs +13 -0
- data/sig/collection/collections.rbs +112 -0
- data/sig/collection/config.rbs +69 -0
- data/sig/collection/installer.rbs +15 -0
- data/sig/collection.rbs +4 -0
- data/sig/environment_loader.rbs +3 -0
- data/sig/polyfill.rbs +12 -3
- data/sig/repository.rbs +4 -0
- data/stdlib/digest/0/digest.rbs +418 -0
- data/stdlib/objspace/0/objspace.rbs +406 -0
- data/stdlib/openssl/0/openssl.rbs +1 -1
- data/stdlib/tempfile/0/tempfile.rbs +270 -0
- data/steep/Gemfile.lock +10 -10
- metadata +24 -3
@@ -0,0 +1,406 @@
|
|
1
|
+
# The objspace library extends the ObjectSpace module and adds several methods
|
2
|
+
# to get internal statistic information about object/memory management.
|
3
|
+
#
|
4
|
+
# You need to `require 'objspace'` to use this extension module.
|
5
|
+
#
|
6
|
+
# Generally, you *SHOULD NOT* use this library if you do not know about the MRI
|
7
|
+
# implementation. Mainly, this library is for (memory) profiler developers and
|
8
|
+
# MRI developers who need to know about MRI memory usage.
|
9
|
+
# The ObjectSpace module contains a number of routines that interact with the
|
10
|
+
# garbage collection facility and allow you to traverse all living objects with
|
11
|
+
# an iterator.
|
12
|
+
#
|
13
|
+
# ObjectSpace also provides support for object finalizers, procs that will be
|
14
|
+
# called when a specific object is about to be destroyed by garbage collection.
|
15
|
+
# See the documentation for `ObjectSpace.define_finalizer` for important
|
16
|
+
# information on how to use this method correctly.
|
17
|
+
#
|
18
|
+
# a = "A"
|
19
|
+
# b = "B"
|
20
|
+
#
|
21
|
+
# ObjectSpace.define_finalizer(a, proc {|id| puts "Finalizer one on #{id}" })
|
22
|
+
# ObjectSpace.define_finalizer(b, proc {|id| puts "Finalizer two on #{id}" })
|
23
|
+
#
|
24
|
+
# a = nil
|
25
|
+
# b = nil
|
26
|
+
#
|
27
|
+
# *produces:*
|
28
|
+
#
|
29
|
+
# Finalizer two on 537763470
|
30
|
+
# Finalizer one on 537763480
|
31
|
+
module ObjectSpace
|
32
|
+
# Returns the class for the given `object`.
|
33
|
+
#
|
34
|
+
# class A
|
35
|
+
# def foo
|
36
|
+
# ObjectSpace::trace_object_allocations do
|
37
|
+
# obj = Object.new
|
38
|
+
# p "#{ObjectSpace::allocation_class_path(obj)}"
|
39
|
+
# end
|
40
|
+
# end
|
41
|
+
# end
|
42
|
+
#
|
43
|
+
# A.new.foo #=> "Class"
|
44
|
+
#
|
45
|
+
# See ::trace_object_allocations for more information and examples.
|
46
|
+
#
|
47
|
+
def self.allocation_class_path: (untyped) -> String
|
48
|
+
|
49
|
+
# Returns garbage collector generation for the given `object`.
|
50
|
+
#
|
51
|
+
# class B
|
52
|
+
# include ObjectSpace
|
53
|
+
#
|
54
|
+
# def foo
|
55
|
+
# trace_object_allocations do
|
56
|
+
# obj = Object.new
|
57
|
+
# p "Generation is #{allocation_generation(obj)}"
|
58
|
+
# end
|
59
|
+
# end
|
60
|
+
# end
|
61
|
+
#
|
62
|
+
# B.new.foo #=> "Generation is 3"
|
63
|
+
#
|
64
|
+
# See ::trace_object_allocations for more information and examples.
|
65
|
+
#
|
66
|
+
def self.allocation_generation: (untyped) -> (Integer | nil)
|
67
|
+
|
68
|
+
# Returns the method identifier for the given `object`.
|
69
|
+
#
|
70
|
+
# class A
|
71
|
+
# include ObjectSpace
|
72
|
+
#
|
73
|
+
# def foo
|
74
|
+
# trace_object_allocations do
|
75
|
+
# obj = Object.new
|
76
|
+
# p "#{allocation_class_path(obj)}##{allocation_method_id(obj)}"
|
77
|
+
# end
|
78
|
+
# end
|
79
|
+
# end
|
80
|
+
#
|
81
|
+
# A.new.foo #=> "Class#new"
|
82
|
+
#
|
83
|
+
# See ::trace_object_allocations for more information and examples.
|
84
|
+
#
|
85
|
+
def self.allocation_method_id: (untyped) -> Symbol
|
86
|
+
|
87
|
+
# Returns the source file origin from the given `object`.
|
88
|
+
#
|
89
|
+
# See ::trace_object_allocations for more information and examples.
|
90
|
+
#
|
91
|
+
def self.allocation_sourcefile: (untyped) -> String
|
92
|
+
|
93
|
+
# Returns the original line from source for from the given `object`.
|
94
|
+
#
|
95
|
+
# See ::trace_object_allocations for more information and examples.
|
96
|
+
#
|
97
|
+
def self.allocation_sourceline: (untyped) -> Integer
|
98
|
+
|
99
|
+
# Counts objects for each `T_IMEMO` type.
|
100
|
+
#
|
101
|
+
# This method is only for MRI developers interested in performance and memory
|
102
|
+
# usage of Ruby programs.
|
103
|
+
#
|
104
|
+
# It returns a hash as:
|
105
|
+
#
|
106
|
+
# {:imemo_ifunc=>8,
|
107
|
+
# :imemo_svar=>7,
|
108
|
+
# :imemo_cref=>509,
|
109
|
+
# :imemo_memo=>1,
|
110
|
+
# :imemo_throw_data=>1}
|
111
|
+
#
|
112
|
+
# If the optional argument, result_hash, is given, it is overwritten and
|
113
|
+
# returned. This is intended to avoid probe effect.
|
114
|
+
#
|
115
|
+
# The contents of the returned hash is implementation specific and may change in
|
116
|
+
# the future.
|
117
|
+
#
|
118
|
+
# In this version, keys are symbol objects.
|
119
|
+
#
|
120
|
+
# This method is only expected to work with C Ruby.
|
121
|
+
#
|
122
|
+
def self.count_imemo_objects: (?Hash[Symbol, Integer] result_hash) -> Hash[Symbol, Integer]
|
123
|
+
|
124
|
+
# Counts nodes for each node type.
|
125
|
+
#
|
126
|
+
# This method is only for MRI developers interested in performance and memory
|
127
|
+
# usage of Ruby programs.
|
128
|
+
#
|
129
|
+
# It returns a hash as:
|
130
|
+
#
|
131
|
+
# {:NODE_METHOD=>2027, :NODE_FBODY=>1927, :NODE_CFUNC=>1798, ...}
|
132
|
+
#
|
133
|
+
# If the optional argument, result_hash, is given, it is overwritten and
|
134
|
+
# returned. This is intended to avoid probe effect.
|
135
|
+
#
|
136
|
+
# Note: The contents of the returned hash is implementation defined. It may be
|
137
|
+
# changed in future.
|
138
|
+
#
|
139
|
+
# This method is only expected to work with C Ruby.
|
140
|
+
#
|
141
|
+
def self.count_nodes: (?Hash[Symbol, Integer] result_hash) -> Hash[Symbol, Integer]
|
142
|
+
|
143
|
+
# Counts objects size (in bytes) for each type.
|
144
|
+
#
|
145
|
+
# Note that this information is incomplete. You need to deal with this
|
146
|
+
# information as only a **HINT**. Especially, total size of T_DATA may be
|
147
|
+
# wrong.
|
148
|
+
#
|
149
|
+
# It returns a hash as:
|
150
|
+
# {:TOTAL=>1461154, :T_CLASS=>158280, :T_MODULE=>20672, :T_STRING=>527249, ...}
|
151
|
+
#
|
152
|
+
# If the optional argument, result_hash, is given, it is overwritten and
|
153
|
+
# returned. This is intended to avoid probe effect.
|
154
|
+
#
|
155
|
+
# The contents of the returned hash is implementation defined. It may be changed
|
156
|
+
# in future.
|
157
|
+
#
|
158
|
+
# This method is only expected to work with C Ruby.
|
159
|
+
#
|
160
|
+
def self.count_objects_size: (?Hash[Symbol, Integer] result_hash) -> Hash[Symbol, Integer]
|
161
|
+
|
162
|
+
# Counts symbols for each Symbol type.
|
163
|
+
#
|
164
|
+
# This method is only for MRI developers interested in performance and memory
|
165
|
+
# usage of Ruby programs.
|
166
|
+
#
|
167
|
+
# If the optional argument, result_hash, is given, it is overwritten and
|
168
|
+
# returned. This is intended to avoid probe effect.
|
169
|
+
#
|
170
|
+
# Note: The contents of the returned hash is implementation defined. It may be
|
171
|
+
# changed in future.
|
172
|
+
#
|
173
|
+
# This method is only expected to work with C Ruby.
|
174
|
+
#
|
175
|
+
# On this version of MRI, they have 3 types of Symbols (and 1 total counts).
|
176
|
+
#
|
177
|
+
# * mortal_dynamic_symbol: GC target symbols (collected by GC)
|
178
|
+
# * immortal_dynamic_symbol: Immortal symbols promoted from dynamic symbols (do not collected by GC)
|
179
|
+
# * immortal_static_symbol: Immortal symbols (do not collected by GC)
|
180
|
+
# * immortal_symbol: total immortal symbols (immortal_dynamic_symbol+immortal_static_symbol)
|
181
|
+
#
|
182
|
+
def self.count_symbols: (?Hash[Symbol, Integer] result_hash) -> Hash[Symbol, Integer]
|
183
|
+
|
184
|
+
# Counts objects for each `T_DATA` type.
|
185
|
+
#
|
186
|
+
# This method is only for MRI developers interested in performance and memory
|
187
|
+
# usage of Ruby programs.
|
188
|
+
#
|
189
|
+
# It returns a hash as:
|
190
|
+
#
|
191
|
+
# {RubyVM::InstructionSequence=>504, :parser=>5, :barrier=>6,
|
192
|
+
# :mutex=>6, Proc=>60, RubyVM::Env=>57, Mutex=>1, Encoding=>99,
|
193
|
+
# ThreadGroup=>1, Binding=>1, Thread=>1, RubyVM=>1, :iseq=>1,
|
194
|
+
# Random=>1, ARGF.class=>1, Data=>1, :autoload=>3, Time=>2}
|
195
|
+
# # T_DATA objects existing at startup on r32276.
|
196
|
+
#
|
197
|
+
# If the optional argument, result_hash, is given, it is overwritten and
|
198
|
+
# returned. This is intended to avoid probe effect.
|
199
|
+
#
|
200
|
+
# The contents of the returned hash is implementation specific and may change in
|
201
|
+
# the future.
|
202
|
+
#
|
203
|
+
# In this version, keys are Class object or Symbol object.
|
204
|
+
#
|
205
|
+
# If object is kind of normal (accessible) object, the key is Class object. If
|
206
|
+
# object is not a kind of normal (internal) object, the key is symbol name,
|
207
|
+
# registered by rb_data_type_struct.
|
208
|
+
#
|
209
|
+
# This method is only expected to work with C Ruby.
|
210
|
+
#
|
211
|
+
def self.count_tdata_objects: (?Hash[untyped, Integer] result_hash) -> Hash[untyped, Integer]
|
212
|
+
|
213
|
+
def self.dump: (untyped obj, ?output: Symbol) -> (String | File | nil)
|
214
|
+
|
215
|
+
def self.dump_all: (?since: (Integer|nil), ?full: boolish, ?output: Symbol) -> (String | File | nil)
|
216
|
+
|
217
|
+
# MRI specific feature
|
218
|
+
# : Return internal class of obj.
|
219
|
+
#
|
220
|
+
# obj can be an instance of InternalObjectWrapper.
|
221
|
+
#
|
222
|
+
# Note that you should not use this method in your application.
|
223
|
+
#
|
224
|
+
def self.internal_class_of: (untyped) -> Class
|
225
|
+
|
226
|
+
# MRI specific feature
|
227
|
+
# : Return internal super class of cls (Class or Module).
|
228
|
+
#
|
229
|
+
# obj can be an instance of InternalObjectWrapper.
|
230
|
+
#
|
231
|
+
# Note that you should not use this method in your application.
|
232
|
+
#
|
233
|
+
def self.internal_super_of: (untyped) -> untyped
|
234
|
+
|
235
|
+
# Return consuming memory size of obj in bytes.
|
236
|
+
#
|
237
|
+
# Note that the return size is incomplete. You need to deal with this
|
238
|
+
# information as only a **HINT**. Especially, the size of `T_DATA` may not be
|
239
|
+
# correct.
|
240
|
+
#
|
241
|
+
# This method is only expected to work with C Ruby.
|
242
|
+
#
|
243
|
+
# From Ruby 2.2, memsize_of(obj) returns a memory size includes sizeof(RVALUE).
|
244
|
+
#
|
245
|
+
def self.memsize_of: (untyped) -> Integer
|
246
|
+
|
247
|
+
# Return consuming memory size of all living objects in bytes.
|
248
|
+
#
|
249
|
+
# If `klass` (should be Class object) is given, return the total memory size of
|
250
|
+
# instances of the given class.
|
251
|
+
#
|
252
|
+
# Note that the returned size is incomplete. You need to deal with this
|
253
|
+
# information as only a **HINT**. Especially, the size of `T_DATA` may not be
|
254
|
+
# correct.
|
255
|
+
#
|
256
|
+
# Note that this method does **NOT** return total malloc'ed memory size.
|
257
|
+
#
|
258
|
+
# This method can be defined by the following Ruby code:
|
259
|
+
#
|
260
|
+
# def memsize_of_all klass = false
|
261
|
+
# total = 0
|
262
|
+
# ObjectSpace.each_object{|e|
|
263
|
+
# total += ObjectSpace.memsize_of(e) if klass == false || e.kind_of?(klass)
|
264
|
+
# }
|
265
|
+
# total
|
266
|
+
# end
|
267
|
+
#
|
268
|
+
# This method is only expected to work with C Ruby.
|
269
|
+
#
|
270
|
+
def self.memsize_of_all: (?Class) -> Integer
|
271
|
+
|
272
|
+
# MRI specific feature
|
273
|
+
# : Return all reachable objects from `obj'.
|
274
|
+
#
|
275
|
+
#
|
276
|
+
# This method returns all reachable objects from `obj'.
|
277
|
+
#
|
278
|
+
# If `obj' has two or more references to the same object `x', then returned
|
279
|
+
# array only includes one `x' object.
|
280
|
+
#
|
281
|
+
# If `obj' is a non-markable (non-heap management) object such as true, false,
|
282
|
+
# nil, symbols and Fixnums (and Flonum) then it simply returns nil.
|
283
|
+
#
|
284
|
+
# If `obj' has references to an internal object, then it returns instances of
|
285
|
+
# ObjectSpace::InternalObjectWrapper class. This object contains a reference to
|
286
|
+
# an internal object and you can check the type of internal object with `type'
|
287
|
+
# method.
|
288
|
+
#
|
289
|
+
# If `obj' is instance of ObjectSpace::InternalObjectWrapper class, then this
|
290
|
+
# method returns all reachable object from an internal object, which is pointed
|
291
|
+
# by `obj'.
|
292
|
+
#
|
293
|
+
# With this method, you can find memory leaks.
|
294
|
+
#
|
295
|
+
# This method is only expected to work except with C Ruby.
|
296
|
+
#
|
297
|
+
# Example:
|
298
|
+
# ObjectSpace.reachable_objects_from(['a', 'b', 'c'])
|
299
|
+
# #=> [Array, 'a', 'b', 'c']
|
300
|
+
#
|
301
|
+
# ObjectSpace.reachable_objects_from(['a', 'a', 'a'])
|
302
|
+
# #=> [Array, 'a', 'a', 'a'] # all 'a' strings have different object id
|
303
|
+
#
|
304
|
+
# ObjectSpace.reachable_objects_from([v = 'a', v, v])
|
305
|
+
# #=> [Array, 'a']
|
306
|
+
#
|
307
|
+
# ObjectSpace.reachable_objects_from(1)
|
308
|
+
# #=> nil # 1 is not markable (heap managed) object
|
309
|
+
#
|
310
|
+
def self.reachable_objects_from: (untyped) -> ([ untyped ] | nil)
|
311
|
+
|
312
|
+
# MRI specific feature
|
313
|
+
# : Return all reachable objects from root.
|
314
|
+
#
|
315
|
+
#
|
316
|
+
def self.reachable_objects_from_root: () -> Hash[String, untyped]
|
317
|
+
|
318
|
+
# Starts tracing object allocations from the ObjectSpace extension module.
|
319
|
+
#
|
320
|
+
# For example:
|
321
|
+
#
|
322
|
+
# require 'objspace'
|
323
|
+
#
|
324
|
+
# class C
|
325
|
+
# include ObjectSpace
|
326
|
+
#
|
327
|
+
# def foo
|
328
|
+
# trace_object_allocations do
|
329
|
+
# obj = Object.new
|
330
|
+
# p "#{allocation_sourcefile(obj)}:#{allocation_sourceline(obj)}"
|
331
|
+
# end
|
332
|
+
# end
|
333
|
+
# end
|
334
|
+
#
|
335
|
+
# C.new.foo #=> "objtrace.rb:8"
|
336
|
+
#
|
337
|
+
# This example has included the ObjectSpace module to make it easier to read,
|
338
|
+
# but you can also use the ::trace_object_allocations notation (recommended).
|
339
|
+
#
|
340
|
+
# Note that this feature introduces a huge performance decrease and huge memory
|
341
|
+
# consumption.
|
342
|
+
#
|
343
|
+
def self.trace_object_allocations: () { (untyped) -> untyped } -> untyped
|
344
|
+
|
345
|
+
# Clear recorded tracing information.
|
346
|
+
#
|
347
|
+
def self.trace_object_allocations_clear: () -> void
|
348
|
+
|
349
|
+
def self.trace_object_allocations_debug_start: () -> void
|
350
|
+
|
351
|
+
# Starts tracing object allocations.
|
352
|
+
#
|
353
|
+
def self.trace_object_allocations_start: () -> void
|
354
|
+
|
355
|
+
# Stop tracing object allocations.
|
356
|
+
#
|
357
|
+
# Note that if ::trace_object_allocations_start is called n-times, then tracing
|
358
|
+
# will stop after calling ::trace_object_allocations_stop n-times.
|
359
|
+
#
|
360
|
+
def self.trace_object_allocations_stop: () -> void
|
361
|
+
|
362
|
+
private
|
363
|
+
|
364
|
+
# Dump the contents of a ruby object as JSON.
|
365
|
+
#
|
366
|
+
# This method is only expected to work with C Ruby. This is an experimental
|
367
|
+
# method and is subject to change. In particular, the function signature and
|
368
|
+
# output format are not guaranteed to be compatible in future versions of ruby.
|
369
|
+
#
|
370
|
+
def dump: (untyped obj, ?output: Symbol) -> (String|File|nil)
|
371
|
+
|
372
|
+
# Dump the contents of the ruby heap as JSON.
|
373
|
+
#
|
374
|
+
# *since* must be a non-negative integer or `nil`.
|
375
|
+
#
|
376
|
+
# If *since* is a positive integer, only objects of that generation and newer
|
377
|
+
# generations are dumped. The current generation can be accessed using
|
378
|
+
# GC::count.
|
379
|
+
#
|
380
|
+
# Objects that were allocated without object allocation tracing enabled are
|
381
|
+
# ignored. See ::trace_object_allocations for more information and examples.
|
382
|
+
#
|
383
|
+
# If *since* is omitted or is `nil`, all objects are dumped.
|
384
|
+
#
|
385
|
+
# This method is only expected to work with C Ruby. This is an experimental
|
386
|
+
# method and is subject to change. In particular, the function signature and
|
387
|
+
# output format are not guaranteed to be compatible in future versions of ruby.
|
388
|
+
#
|
389
|
+
def dump_all: (?since: (Integer|nil), ?full: boolish, ?output: Symbol) -> (String|File|nil)
|
390
|
+
|
391
|
+
def memsize_of: (untyped) -> Integer
|
392
|
+
|
393
|
+
def memsize_of_all: (?class) -> Integer
|
394
|
+
|
395
|
+
def reachable_objects_from: (untyped) -> ([ untyped ] | nil)
|
396
|
+
|
397
|
+
def reachable_objects_from_root: () -> Hash[String, untyped]
|
398
|
+
|
399
|
+
def trace_object_allocations_clear: () -> void
|
400
|
+
|
401
|
+
def trace_object_allocations_debug_start: () -> void
|
402
|
+
|
403
|
+
def trace_object_allocations_start: () -> void
|
404
|
+
|
405
|
+
def trace_object_allocations_stop: () -> void
|
406
|
+
end
|
@@ -0,0 +1,270 @@
|
|
1
|
+
# A utility class for managing temporary files. When you create a Tempfile
|
2
|
+
# object, it will create a temporary file with a unique filename. A Tempfile
|
3
|
+
# objects behaves just like a File object, and you can perform all the usual
|
4
|
+
# file operations on it: reading data, writing data, changing its permissions,
|
5
|
+
# etc. So although this class does not explicitly document all instance methods
|
6
|
+
# supported by File, you can in fact call any File instance method on a Tempfile
|
7
|
+
# object.
|
8
|
+
#
|
9
|
+
# ## Synopsis
|
10
|
+
#
|
11
|
+
# require 'tempfile'
|
12
|
+
#
|
13
|
+
# file = Tempfile.new('foo')
|
14
|
+
# file.path # => A unique filename in the OS's temp directory,
|
15
|
+
# # e.g.: "/tmp/foo.24722.0"
|
16
|
+
# # This filename contains 'foo' in its basename.
|
17
|
+
# file.write("hello world")
|
18
|
+
# file.rewind
|
19
|
+
# file.read # => "hello world"
|
20
|
+
# file.close
|
21
|
+
# file.unlink # deletes the temp file
|
22
|
+
#
|
23
|
+
# ## Good practices
|
24
|
+
#
|
25
|
+
# ### Explicit close
|
26
|
+
#
|
27
|
+
# When a Tempfile object is garbage collected, or when the Ruby interpreter
|
28
|
+
# exits, its associated temporary file is automatically deleted. This means
|
29
|
+
# that's it's unnecessary to explicitly delete a Tempfile after use, though it's
|
30
|
+
# good practice to do so: not explicitly deleting unused Tempfiles can
|
31
|
+
# potentially leave behind large amounts of tempfiles on the filesystem until
|
32
|
+
# they're garbage collected. The existence of these temp files can make it
|
33
|
+
# harder to determine a new Tempfile filename.
|
34
|
+
#
|
35
|
+
# Therefore, one should always call #unlink or close in an ensure block, like
|
36
|
+
# this:
|
37
|
+
#
|
38
|
+
# file = Tempfile.new('foo')
|
39
|
+
# begin
|
40
|
+
# # ...do something with file...
|
41
|
+
# ensure
|
42
|
+
# file.close
|
43
|
+
# file.unlink # deletes the temp file
|
44
|
+
# end
|
45
|
+
#
|
46
|
+
# Tempfile.create { ... } exists for this purpose and is more convenient to use.
|
47
|
+
# Note that Tempfile.create returns a File instance instead of a Tempfile, which
|
48
|
+
# also avoids the overhead and complications of delegation.
|
49
|
+
#
|
50
|
+
# Tempfile.open('foo') do |file|
|
51
|
+
# # ...do something with file...
|
52
|
+
# end
|
53
|
+
#
|
54
|
+
# ### Unlink after creation
|
55
|
+
#
|
56
|
+
# On POSIX systems, it's possible to unlink a file right after creating it, and
|
57
|
+
# before closing it. This removes the filesystem entry without closing the file
|
58
|
+
# handle, so it ensures that only the processes that already had the file handle
|
59
|
+
# open can access the file's contents. It's strongly recommended that you do
|
60
|
+
# this if you do not want any other processes to be able to read from or write
|
61
|
+
# to the Tempfile, and you do not need to know the Tempfile's filename either.
|
62
|
+
#
|
63
|
+
# For example, a practical use case for unlink-after-creation would be this: you
|
64
|
+
# need a large byte buffer that's too large to comfortably fit in RAM, e.g. when
|
65
|
+
# you're writing a web server and you want to buffer the client's file upload
|
66
|
+
# data.
|
67
|
+
#
|
68
|
+
# Please refer to #unlink for more information and a code example.
|
69
|
+
#
|
70
|
+
# ## Minor notes
|
71
|
+
#
|
72
|
+
# Tempfile's filename picking method is both thread-safe and inter-process-safe:
|
73
|
+
# it guarantees that no other threads or processes will pick the same filename.
|
74
|
+
#
|
75
|
+
# Tempfile itself however may not be entirely thread-safe. If you access the
|
76
|
+
# same Tempfile object from multiple threads then you should protect it with a
|
77
|
+
# mutex.
|
78
|
+
class Tempfile < File
|
79
|
+
# Creates a temporary file as a usual File object (not a Tempfile). It does not
|
80
|
+
# use finalizer and delegation, which makes it more efficient and reliable.
|
81
|
+
#
|
82
|
+
# If no block is given, this is similar to Tempfile.new except creating File
|
83
|
+
# instead of Tempfile. In that case, the created file is not removed
|
84
|
+
# automatically. You should use File.unlink to remove it.
|
85
|
+
#
|
86
|
+
# If a block is given, then a File object will be constructed, and the block is
|
87
|
+
# invoked with the object as the argument. The File object will be automatically
|
88
|
+
# closed and the temporary file is removed after the block terminates, releasing
|
89
|
+
# all resources that the block created. The call returns the value of the block.
|
90
|
+
#
|
91
|
+
# In any case, all arguments (`basename`, `tmpdir`, `mode`, and `**options`)
|
92
|
+
# will be treated the same as for Tempfile.new.
|
93
|
+
#
|
94
|
+
# Tempfile.create('foo', '/home/temp') do |f|
|
95
|
+
# # ... do something with f ...
|
96
|
+
# end
|
97
|
+
#
|
98
|
+
def self.create: (?String basename, ?String? tmpdir, ?mode: Integer, **untyped) -> File
|
99
|
+
| [A] (?String basename, ?String? tmpdir, ?mode: Integer, **untyped) { (File) -> A } -> A
|
100
|
+
|
101
|
+
# Creates a new Tempfile.
|
102
|
+
#
|
103
|
+
# This method is not recommended and exists mostly for backward compatibility.
|
104
|
+
# Please use Tempfile.create instead, which avoids the cost of delegation, does
|
105
|
+
# not rely on a finalizer, and also unlinks the file when given a block.
|
106
|
+
#
|
107
|
+
# Tempfile.open is still appropriate if you need the Tempfile to be unlinked by
|
108
|
+
# a finalizer and you cannot explicitly know where in the program the Tempfile
|
109
|
+
# can be unlinked safely.
|
110
|
+
#
|
111
|
+
# If no block is given, this is a synonym for Tempfile.new.
|
112
|
+
#
|
113
|
+
# If a block is given, then a Tempfile object will be constructed, and the block
|
114
|
+
# is run with the Tempfile object as argument. The Tempfile object will be
|
115
|
+
# automatically closed after the block terminates. However, the file will
|
116
|
+
# **not** be unlinked and needs to be manually unlinked with Tempfile#close! or
|
117
|
+
# Tempfile#unlink. The finalizer will try to unlink but should not be relied
|
118
|
+
# upon as it can keep the file on the disk much longer than intended. For
|
119
|
+
# instance, on CRuby, finalizers can be delayed due to conservative stack
|
120
|
+
# scanning and references left in unused memory.
|
121
|
+
#
|
122
|
+
# The call returns the value of the block.
|
123
|
+
#
|
124
|
+
# In any case, all arguments (`*args`) will be passed to Tempfile.new.
|
125
|
+
#
|
126
|
+
# Tempfile.open('foo', '/home/temp') do |f|
|
127
|
+
# # ... do something with f ...
|
128
|
+
# end
|
129
|
+
#
|
130
|
+
# # Equivalent:
|
131
|
+
# f = Tempfile.open('foo', '/home/temp')
|
132
|
+
# begin
|
133
|
+
# # ... do something with f ...
|
134
|
+
# ensure
|
135
|
+
# f.close
|
136
|
+
# end
|
137
|
+
#
|
138
|
+
def self.open: (*untyped args, **untyped) -> Tempfile
|
139
|
+
| [A] (*untyped args, **untyped) { (Tempfile) -> A } -> A
|
140
|
+
|
141
|
+
public
|
142
|
+
|
143
|
+
# Closes the file. If `unlink_now` is true, then the file will be unlinked
|
144
|
+
# (deleted) after closing. Of course, you can choose to later call #unlink if
|
145
|
+
# you do not unlink it now.
|
146
|
+
#
|
147
|
+
# If you don't explicitly unlink the temporary file, the removal will be delayed
|
148
|
+
# until the object is finalized.
|
149
|
+
#
|
150
|
+
def close: (?boolish unlink_now) -> void
|
151
|
+
|
152
|
+
# Closes and unlinks (deletes) the file. Has the same effect as called
|
153
|
+
# `close(true)`.
|
154
|
+
#
|
155
|
+
def close!: () -> void
|
156
|
+
|
157
|
+
alias delete unlink
|
158
|
+
|
159
|
+
def inspect: () -> String
|
160
|
+
|
161
|
+
alias length size
|
162
|
+
|
163
|
+
# Opens or reopens the file with mode "r+".
|
164
|
+
#
|
165
|
+
def open: () -> File
|
166
|
+
|
167
|
+
# Returns the full path name of the temporary file. This will be nil if #unlink
|
168
|
+
# has been called.
|
169
|
+
#
|
170
|
+
def path: () -> String?
|
171
|
+
|
172
|
+
# Returns the size of the temporary file. As a side effect, the IO buffer is
|
173
|
+
# flushed before determining the size.
|
174
|
+
#
|
175
|
+
def size: () -> Integer
|
176
|
+
|
177
|
+
# Unlinks (deletes) the file from the filesystem. One should always unlink the
|
178
|
+
# file after using it, as is explained in the "Explicit close" good practice
|
179
|
+
# section in the Tempfile overview:
|
180
|
+
#
|
181
|
+
# file = Tempfile.new('foo')
|
182
|
+
# begin
|
183
|
+
# # ...do something with file...
|
184
|
+
# ensure
|
185
|
+
# file.close
|
186
|
+
# file.unlink # deletes the temp file
|
187
|
+
# end
|
188
|
+
#
|
189
|
+
# ### Unlink-before-close
|
190
|
+
#
|
191
|
+
# On POSIX systems it's possible to unlink a file before closing it. This
|
192
|
+
# practice is explained in detail in the Tempfile overview (section "Unlink
|
193
|
+
# after creation"); please refer there for more information.
|
194
|
+
#
|
195
|
+
# However, unlink-before-close may not be supported on non-POSIX operating
|
196
|
+
# systems. Microsoft Windows is the most notable case: unlinking a non-closed
|
197
|
+
# file will result in an error, which this method will silently ignore. If you
|
198
|
+
# want to practice unlink-before-close whenever possible, then you should write
|
199
|
+
# code like this:
|
200
|
+
#
|
201
|
+
# file = Tempfile.new('foo')
|
202
|
+
# file.unlink # On Windows this silently fails.
|
203
|
+
# begin
|
204
|
+
# # ... do something with file ...
|
205
|
+
# ensure
|
206
|
+
# file.close! # Closes the file handle. If the file wasn't unlinked
|
207
|
+
# # because #unlink failed, then this method will attempt
|
208
|
+
# # to do so again.
|
209
|
+
# end
|
210
|
+
#
|
211
|
+
def unlink: () -> void
|
212
|
+
|
213
|
+
class Remover
|
214
|
+
public
|
215
|
+
|
216
|
+
def call: (*untyped args) -> void
|
217
|
+
|
218
|
+
private
|
219
|
+
|
220
|
+
def initialize: (::Tempfile tmpfile) -> void
|
221
|
+
end
|
222
|
+
|
223
|
+
private
|
224
|
+
|
225
|
+
# Creates a temporary file with permissions 0600 (= only readable and writable
|
226
|
+
# by the owner) and opens it with mode "w+".
|
227
|
+
#
|
228
|
+
# It is recommended to use Tempfile.create { ... } instead when possible,
|
229
|
+
# because that method avoids the cost of delegation and does not rely on a
|
230
|
+
# finalizer to close and unlink the file, which is unreliable.
|
231
|
+
#
|
232
|
+
# The `basename` parameter is used to determine the name of the temporary file.
|
233
|
+
# You can either pass a String or an Array with 2 String elements. In the former
|
234
|
+
# form, the temporary file's base name will begin with the given string. In the
|
235
|
+
# latter form, the temporary file's base name will begin with the array's first
|
236
|
+
# element, and end with the second element. For example:
|
237
|
+
#
|
238
|
+
# file = Tempfile.new('hello')
|
239
|
+
# file.path # => something like: "/tmp/hello2843-8392-92849382--0"
|
240
|
+
#
|
241
|
+
# # Use the Array form to enforce an extension in the filename:
|
242
|
+
# file = Tempfile.new(['hello', '.jpg'])
|
243
|
+
# file.path # => something like: "/tmp/hello2843-8392-92849382--0.jpg"
|
244
|
+
#
|
245
|
+
# The temporary file will be placed in the directory as specified by the
|
246
|
+
# `tmpdir` parameter. By default, this is `Dir.tmpdir`.
|
247
|
+
#
|
248
|
+
# file = Tempfile.new('hello', '/home/aisaka')
|
249
|
+
# file.path # => something like: "/home/aisaka/hello2843-8392-92849382--0"
|
250
|
+
#
|
251
|
+
# You can also pass an options hash. Under the hood, Tempfile creates the
|
252
|
+
# temporary file using `File.open`. These options will be passed to `File.open`.
|
253
|
+
# This is mostly useful for specifying encoding options, e.g.:
|
254
|
+
#
|
255
|
+
# Tempfile.new('hello', '/home/aisaka', encoding: 'ascii-8bit')
|
256
|
+
#
|
257
|
+
# # You can also omit the 'tmpdir' parameter:
|
258
|
+
# Tempfile.new('hello', encoding: 'ascii-8bit')
|
259
|
+
#
|
260
|
+
# Note: `mode` keyword argument, as accepted by Tempfile, can only be numeric,
|
261
|
+
# combination of the modes defined in File::Constants.
|
262
|
+
#
|
263
|
+
# ### Exceptions
|
264
|
+
#
|
265
|
+
# If Tempfile.new cannot find a unique filename within a limited number of
|
266
|
+
# tries, then it will raise an exception.
|
267
|
+
#
|
268
|
+
def self.new: (?String basename, ?String? tmpdir, ?mode: Integer, **untyped) -> instance
|
269
|
+
| [A] (?String basename, ?String? tmpdir, ?mode: Integer, **untyped) { (instance) -> A } -> A
|
270
|
+
end
|