| 1 | package IO::SigGuard; | ||
| 2 | |||
| 3 | =encoding utf-8 | ||
| 4 | |||
| 5 | =head1 NAME | ||
| 6 | |||
| 7 | IO::SigGuard - SA_RESTART in pure Perl | ||
| 8 | |||
| 9 | =head1 SYNOPSIS | ||
| 10 | |||
| 11 | IO::SigGuard::sysread( $fh, $buf, $size ); | ||
| 12 | IO::SigGuard::sysread( $fh, $buf, $size, $offset ); | ||
| 13 | |||
| 14 | IO::SigGuard::syswrite( $fh, $buf ); | ||
| 15 | IO::SigGuard::syswrite( $fh, $buf, $len ); | ||
| 16 | IO::SigGuard::syswrite( $fh, $buf, $len, $offset ); | ||
| 17 | |||
| 18 | IO::SigGuard::send( $fh, $msg, $flags ); | ||
| 19 | IO::SigGuard::send( $fh, $msg, $flags, $to ); | ||
| 20 | |||
| 21 | IO::SigGuard::select( $read, $write, $exc, $timeout ); | ||
| 22 | |||
| 23 | =head1 DESCRIPTION | ||
| 24 | |||
| 25 | C<perldoc perlipc> describes how Perl versions from 5.8.0 onward disable | ||
| 26 | the OS’s SA_RESTART flag when installing Perl signal handlers. | ||
| 27 | |||
| 28 | This module imitates that pattern in pure Perl: it does an automatic | ||
| 29 | restart when a signal interrupts an operation so you can avoid | ||
| 30 | the generally-useless EINTR error when using | ||
| 31 | C<sysread()>, C<syswrite()>, and C<select()>. | ||
| 32 | |||
| 33 | For this to work, whatever signal handler you implement will need to break | ||
| 34 | out of this module, probably via either C<die()> or C<exit()>. | ||
| 35 | |||
| 36 | =head1 ABOUT C<sysread()> and C<syswrite()> | ||
| 37 | |||
| 38 | Other than that you’ll never see EINTR and that | ||
| 39 | there are no function prototypes used (i.e., you need parentheses on | ||
| 40 | all invocations), C<sysread()> and C<syswrite()> | ||
| 41 | work exactly the same as Perl’s equivalent built-ins. | ||
| 42 | |||
| 43 | =head1 LAZY-LOADING | ||
| 44 | |||
| 45 | As of version 0.13 this module’s functions lazy-load by default. To have | ||
| 46 | functionality loaded at compile time give the function name to the import | ||
| 47 | logic, e.g.: | ||
| 48 | |||
| 49 | use IO::SigGuard qw(send recv); | ||
| 50 | |||
| 51 | =head1 ABOUT C<select()> | ||
| 52 | |||
| 53 | To handle EINTR, C<IO::SigGuard::select()> has to subtract the elapsed time | ||
| 54 | from the given timeout then repeat the internal C<select()>. Because | ||
| 55 | the C<select()> built-in’s C<$timeleft> return is not reliable across | ||
| 56 | all platforms, we have to compute the elapsed time ourselves. By default the | ||
| 57 | only means of doing this is the C<time()> built-in, which can only measure | ||
| 58 | individual seconds. | ||
| 59 | |||
| 60 | This works, but there are two ways to make it more accurate: | ||
| 61 | |||
| 62 | =over | ||
| 63 | |||
| 64 | =item * Have L<Time::HiRes> loaded, and C<IO::SigGuard::select()> will use that | ||
| 65 | module rather than the C<time()> built-in. | ||
| 66 | |||
| 67 | =item * Set C<$IO::SigGuard::TIME_CR> to a compatible code reference. This is | ||
| 68 | useful, e.g., if you have your own logic to do the equivalent of | ||
| 69 | L<Time::HiRes>—for example, in Linux you may prefer to call the C<gettimeofday> | ||
| 70 | system call directly from Perl to avoid L<Time::HiRes>’s XS overhead. | ||
| 71 | |||
| 72 | =back | ||
| 73 | |||
| 74 | In scalar contact, C<IO::SigGuard::select()> is a drop-in replacement | ||
| 75 | for Perl’s 4-argument built-in. | ||
| 76 | |||
| 77 | In list context, there may be discrepancies re the C<$timeleft> value | ||
| 78 | that Perl returns from a call to C<select>. As per Perl’s documentation | ||
| 79 | this value is generally not reliable anyway, though, so that shouldn’t be a | ||
| 80 | big deal. In fact, on systems like MacOS where the built-in’s C<$timeleft> | ||
| 81 | is completely useless, IO::SigGuard’s return is actually B<better> since it | ||
| 82 | does provide at least a rough estimate of how much of the given timeout value | ||
| 83 | is left. | ||
| 84 | |||
| 85 | See C<perlport> for portability notes for C<select>. | ||
| 86 | |||
| 87 | =head1 TODO | ||
| 88 | |||
| 89 | This pattern could probably be extended to other system calls that can | ||
| 90 | receive EINTR. I’ll consider adding new calls as requested. | ||
| 91 | |||
| 92 | =cut | ||
| 93 | |||
| 94 | 10 | ▶ | use strict; |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 95 | 10 | ▶ | use warnings; |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 96 | |||
| 97 | 10 | ▶ | use Errno (); |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 98 | |||
| 99 | 10 | our $VERSION = '0.15'; | |
| 100 | |||
| 101 | #As light as possible … | ||
| 102 | |||
| 103 | 10 | my $result; | |
| 104 | |||
| 105 | 1 | ▶ | sub import { |
|
Subroutine
import: called CC=2 SCAR=6.9
| |||
| 106 | 1 | shift; | |
| 107 | |||
| 108 | 1 | require "IO/SigGuard/$_.pm" for @_; | |
| 109 | |||
| 110 | 1 | return; | |
| 111 | } | ||
| 112 | |||
| 113 | 10 | our $AUTOLOAD; | |
| 114 | |||
| 115 | 10 | ▶ | sub AUTOLOAD { |
|
Subroutine
AUTOLOAD: called CC=1 SCAR=0.0
| |||
| 116 | 10 | $AUTOLOAD = substr( $AUTOLOAD, 1 + rindex($AUTOLOAD, ':') ); | |
| 117 | |||
| 118 | 10 | require "IO/SigGuard/$AUTOLOAD.pm"; | |
| 119 | |||
| 120 | 10 | goto &{ IO::SigGuard->can($AUTOLOAD) }; | |
| 121 | } | ||
| 122 | |||
| 123 | =head1 REPOSITORY | ||
| 124 | |||
| 125 | L<https://github.com/FGasper/p5-IO-SigGuard> | ||
| 126 | |||
| 127 | =head1 AUTHOR | ||
| 128 | |||
| 129 | Felipe Gasper (FELIPE) | ||
| 130 | |||
| 131 | … with special thanks to Mario Roy (MARIOROY) for extra testing | ||
| 132 | and a few fixes/improvements. | ||
| 133 | |||
| 134 | =head1 COPYRIGHT | ||
| 135 | |||
| 136 | Copyright 2017 by L<Gasper Software Consulting|http://gaspersoftware.com> | ||
| 137 | |||
| 138 | =head1 LICENSE | ||
| 139 | |||
| 140 | This distribution is released under the same license as Perl. | ||
| 141 | |||
| 142 | =cut | ||
| 143 | |||
| 144 | 10 | 1; | |