U:RDoc::TopLevel[ i I"signals.rdoc:EFcRDoc::Parser::Simpleo:RDoc::Markup::Document: @parts[ S:RDoc::Markup::Heading:
leveli: textI"3Caveats for implementing Signal.trap callbacks;To: RDoc::Markup::BlankLine o: RDoc::Markup::Paragraph;[
I"HAs with implementing signal handlers in C or most other languages, ;TI"Gall code passed to Signal.trap must be reentrant. If you are not ;TI"<familiar with reentrancy, you need to read up on it at ;TI"J{Wikipedia}[https://en.wikipedia.org/wiki/Reentrancy_(computing)] or ;TI"8elsewhere before reading the rest of this document.;T@
o;
;[I"FMost importantly, "thread-safety" does not guarantee reentrancy; ;TI"Dand methods such as Mutex#lock and Mutex#synchronize which are ;TI"=commonly used for thread-safety even prevent reentrancy.;T@
S; ;
i; I",An implementation detail of the Ruby VM;T@
o;
;[ I"LThe Ruby VM defers Signal.trap callbacks from running until it is safe ;TI"Lfor its internal data structures, but it does not know when it is safe ;TI"Hfor data structures in YOUR code. Ruby implements deferred signal ;TI"9handling by registering short C functions with only ;TI"a{async-signal-safe functions}[http://man7.org/linux/man-pages/man7/signal-safety.7.html] as ;TI"Msignal handlers. These short C functions only do enough tell the VM to ;TI"Lrun callbacks registered via Signal.trap later in the main Ruby Thread.;T@
S; ;
i; I"1Unsafe methods to call in Signal.trap blocks;T@
o;
;[I"HWhen in doubt, consider anything not listed as safe below as being ;TI" unsafe.;T@
o:RDoc::Markup::List:
@type: BULLET: @items[ o:RDoc::Markup::ListItem: @label0;[o;
;[I"JMutex#lock, Mutex#synchronize and any code using them are explicitly ;TI"Gunsafe. This includes Monitor in the standard library which uses ;TI"!Mutex to provide reentrancy.;T@
o;;0;[o;
;[I"Dir.chdir with block;T@
o;;0;[o;
;[ I"4any IO write operations when IO#sync is false; ;TI"5including IO#write, IO#write_nonblock, IO#puts. ;TI"EPipes and sockets default to `IO#sync = true', so it is safe to ;TI"/write to them unless IO#sync was disabled.;T@
o;;0;[o;
;[I"JFile#flock, as the underlying flock(2) call is not specified by POSIX;T@
S; ;
i; I"7Commonly safe operations inside Signal.trap blocks;T@
o;;;;[
o;;0;[o;
;[I"EAssignment and retrieval of local, instance, and class variables;T@
o;;0;[o;
;[I"AMost object allocations and initializations of common types ;TI"1including Array, Hash, String, Struct, Time.;T@
o;;0;[o;
;[I"PCommon Array, Hash, String, Struct operations which do not execute a block ;TI"Hare generally safe; but beware if iteration is occurring elsewhere.;T@
o;;0;[o;
;[I"BHash#[], Hash#[]= (unless Hash.new was given an unsafe block);T@
o;;0;[o;
;[I"DThread::Queue#push and Thread::SizedQueue#push (since Ruby 2.1);T@
o;;0;[o;
;[I"GCreating a new Thread via Thread.new/Thread.start can used to get ;TI">around the unusability of Mutexes inside a signal handler;T@
o;;0;[o;
;[I"CSignal.trap is safe to use inside blocks passed to Signal.trap;T@
o;;0;[ o;
;[I">arithmetic on Integer and Float (`+', `-', '%', '*', '/');T@
o;
;[ I"EAdditionally, signal handlers do not run between two successive ;TI"Flocal variable accesses, so shortcuts such as `+=' and `-=' will ;TI"Gnot trigger a data race when used on Integer and Float classes in ;TI"signal handlers.;T@
S; ;
i; I"BSystem call wrapper methods which are safe inside Signal.trap;T@
o;
;[ I")Since Ruby has wrappers around many ;TI"`{async-signal-safe C functions}[http://man7.org/linux/man-pages/man7/signal-safety.7.html] ;TI"Kthe corresponding wrappers for many IO, File, Dir, and Socket methods ;TI"are safe.;T@
o;
;[I"(Incomplete list);T@
o;;;;[#o;;0;[o;
;[I""Dir.chdir (without block arg);To;;0;[o;
;[I"Dir.mkdir;To;;0;[o;
;[I"
Dir.open;To;;0;[o;
;[I"File#truncate;To;;0;[o;
;[I"File.link;To;;0;[o;
;[I"File.open;To;;0;[o;
;[I"File.readlink;To;;0;[o;
;[I"File.rename;To;;0;[o;
;[I"File.stat;To;;0;[o;
;[I"File.symlink;To;;0;[o;
;[I"File.truncate;To;;0;[o;
;[I"File.unlink;To;;0;[o;
;[I"File.utime;To;;0;[o;
;[I"
IO#close;To;;0;[o;
;[I" IO#dup;To;;0;[o;
;[I"
IO#fsync;To;;0;[o;
;[I" IO#read;To;;0;[o;
;[I"IO#read_nonblock;To;;0;[o;
;[I" IO#stat;To;;0;[o;
;[I"IO#sysread;To;;0;[o;
;[I"IO#syswrite;To;;0;[o;
;[I"IO.select;To;;0;[o;
;[I" IO.pipe;To;;0;[o;
;[I"Process.clock_gettime;To;;0;[o;
;[I"Process.exit!;To;;0;[o;
;[I"Process.fork;To;;0;[o;
;[I"Process.kill;To;;0;[o;
;[I"Process.pid;To;;0;[o;
;[I"Process.ppid;To;;0;[o;
;[I"Process.waitpid;To;
;[I"...;T:
@file@:0@omit_headings_from_table_of_contents_below0