1#@!#!123s

: / proc / self / root / opt / alt / ruby34 / share / ri / system / Tempfile /
Filename : cdesc-Tempfile.ri
back
U:RDoc::NormalClass[iI"
Tempfile:ET@I"DelegateClass(File);To:RDoc::Markup::Document:@parts[o;;[5o:RDoc::Markup::Paragraph;[I"2A utility class for managing temporary files.;To:RDoc::Markup::BlankLine�o;	;[I"@There are two kind of methods of creating a temporary file:;T@o:RDoc::Markup::List:
@type:BULLET:@items[o:RDoc::Markup::ListItem:@label0;[o;	;[I""Tempfile.create (recommended);To;;0;[o;	;[I"XTempfile.new and Tempfile.open (mostly for backward compatibility, not recommended);T@o;	;[	I"3Tempfile.create creates a usual \File object. ;TI"1The timing of file deletion is predictable. ;TI"7Also, it supports open-and-unlink technique which ;TI";removes the temporary file immediately after creation.;T@o;	;[I"@Tempfile.new and Tempfile.open creates a \Tempfile object. ;TI"8The created file is removed by the GC (finalizer). ;TI"4The timing of file deletion is not predictable.;T@S:RDoc::Markup::Heading:
leveli:	textI"
Synopsis;T@o:RDoc::Markup::Verbatim;[3I"require 'tempfile'
;TI"
;TI"$# Tempfile.create with a block
;TI"/# The filename are choosen automatically.
;TI"X# (You can specify the prefix and suffix of the filename by an optional argument.)
;TI"Tempfile.create {|f|
;TI"  f.puts "foo"
;TI"  f.rewind
;TI"*  f.read                # => "foo\n"
;TI"B}                       # The file is removed at block exit.
;TI"
;TI"'# Tempfile.create without a block
;TI"6# You need to unlink the file in non-block form.
;TI"f = Tempfile.create
;TI"f.puts "foo"
;TI"
f.close
;TI"<File.unlink(f.path)     # You need to unlink the file.
;TI"
;TI"8# Tempfile.create(anonymous: true) without a block
;TI"*f = Tempfile.create(anonymous: true)
;TI"6# The file is already removed because anonymous.
;TI"Gf.path                  # => "/tmp/"  (no filename since no file)
;TI"f.puts "foo"
;TI"f.rewind
;TI"*f.read                  # => "foo\n"
;TI"
f.close
;TI"
;TI"5# Tempfile.create(anonymous: true) with a block
;TI"+Tempfile.create(anonymous: true) {|f|
;TI"8  # The file is already removed because anonymous.
;TI"G  f.path                # => "/tmp/"  (no filename since no file)
;TI"  f.puts "foo"
;TI"  f.rewind
;TI"*  f.read                # => "foo\n"
;TI"}
;TI"
;TI"5# Not recommended: Tempfile.new without a block
;TI" file = Tempfile.new('foo')
;TI"Gfile.path      # => A unique filename in the OS's temp directory,
;TI"2               #    e.g.: "/tmp/foo.24722.0"
;TI"G               #    This filename contains 'foo' in its basename.
;TI"file.write("hello world")
;TI"file.rewind
;TI"'file.read      # => "hello world"
;TI"file.close
;TI",file.unlink    # deletes the temp file
;T:@format0S;;i;I")About Tempfile.new and Tempfile.open;T@o;	;[I"<This section does not apply to Tempfile.create because ;TI"6it returns a File object (not a Tempfile object).;T@o;	;[I"(When you create a Tempfile object, ;TI"Hit will create a temporary file with a unique filename. A Tempfile ;TI"Pobjects behaves just like a File object, and you can perform all the usual ;TI"Rfile operations on it: reading data, writing data, changing its permissions, ;TI"Setc. So although this class does not explicitly document all instance methods ;TI"Ksupported by File, you can in fact call any File instance method on a ;TI"Tempfile object.;T@o;	;[I"EA Tempfile object has a finalizer to remove the temporary file. ;TI";This means that the temporary file is removed via GC. ;TI"%This can cause several problems:;T@o;;;
;[o;;0;[o;	;[I"_Long GC intervals and conservative GC can accumulate temporary files that are not removed.;To;;0;[o;	;[I"VTemporary files are not removed if Ruby exits abnormally (such as SIGKILL, SEGV).;T@o;	;[I"SThere are legacy good practices for Tempfile.new and Tempfile.open as follows.;T@S;;i;I"Explicit close;T@o;	;[I"OWhen a Tempfile object is garbage collected, or when the Ruby interpreter ;TI"Oexits, its associated temporary file is automatically deleted. This means ;TI"Mthat it's unnecessary to explicitly delete a Tempfile after use, though ;TI"Qit's a good practice to do so: not explicitly deleting unused Tempfiles can ;TI"Mpotentially leave behind a large number of temp files on the filesystem ;TI"Quntil they're garbage collected. The existence of these temp files can make ;TI"4it harder to determine a new Tempfile filename.;T@o;	;[I"QTherefore, one should always call #unlink or close in an ensure block, like ;TI"
this:;T@o;;[I" file = Tempfile.new('foo')
;TI"begin
;TI"'   # ...do something with file...
;TI"ensure
;TI"   file.close
;TI".   file.unlink   # deletes the temp file
;TI"	end
;T;0o;	;[I"TTempfile.create { ... } exists for this purpose and is more convenient to use. ;TI"TNote that Tempfile.create returns a File instance instead of a Tempfile, which ;TI">also avoids the overhead and complications of delegation.;T@o;;[I"&Tempfile.create('foo') do |file|
;TI"'   # ...do something with file...
;TI"	end
;T;0S;;i;I"Unlink after creation;T@o;	;[I"OOn POSIX systems, it's possible to unlink a file right after creating it, ;TI"Nand before closing it. This removes the filesystem entry without closing ;TI"Mthe file handle, so it ensures that only the processes that already had ;TI"Hthe file handle open can access the file's contents. It's strongly ;TI"Lrecommended that you do this if you do not want any other processes to ;TI"Kbe able to read from or write to the Tempfile, and you do not need to ;TI")know the Tempfile's filename either.;T@o;	;[I"XAlso, this guarantees the temporary file is removed even if Ruby exits abnormally. ;TI"SThe OS reclaims the storage for the temporary file when the file is closed or ;TI"5the Ruby process exits (normally or abnormally).;T@o;	;[	I"PFor example, a practical use case for unlink-after-creation would be this: ;TI"Nyou need a large byte buffer that's too large to comfortably fit in RAM, ;TI"Oe.g. when you're writing a web server and you want to buffer the client's ;TI"file upload data.;T@o;	;[I"@`Tempfile.create(anonymous: true)` supports this behavior. ;TI"It also works on Windows.;T@S;;i;I"Minor notes;T@o;	;[I"TTempfile's filename picking method is both thread-safe and inter-process-safe: ;TI"Rit guarantees that no other threads or processes will pick the same filename.;T@o;	;[I"PTempfile itself however may not be entirely thread-safe. If you access the ;TI"Rsame Tempfile object from multiple threads then you should protect it with a ;TI"mutex.;T:
@fileI"lib/tempfile.rb;T:0@omit_headings_from_table_of_contents_below0;0;0[�[U:RDoc::Constant[i�I"VERSION;TI"Tempfile::VERSION;T:public0o;;[o;	;[I"The version;T;@�;0@�@cRDoc::NormalClass0[�[[I"
class;T[[;[[I"create;TI"lib/tempfile.rb;T[I"new;T@�[I"	open;T@�[:protected[�[:private[[I"create_anonymous;T@�[I"create_with_filename;T@�[I"
instance;T[[;[
[I"
close;T@�[I"close!;T@�[I"delete;T@�[I"length;T@�[I"	open;T@�[I"	path;T@�[I"	size;T@�[I"unlink;T@�[;[�[;[�[�[U:RDoc::Context::Section[i�0o;;[�;0;0[@�@�cRDoc::TopLevel