File Coverage

blib/lib/IO/SigGuard.pm
Criterion Covered Total %
statement 16 16 100.0
branch n/a
condition n/a
subroutine 5 5 100.0
pod n/a
total 21 21 100.0


line stmt bran cond sub pod time code
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 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, C, and C.
32              
33             For this to work, whatever signal handler you implement will need to break
34             out of this module, probably via either C or C.
35              
36             =head1 ABOUT C and C
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 and C
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
52              
53             To handle EINTR, C has to subtract the elapsed time
54             from the given timeout then repeat the internal C. Because
55             the C 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 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 loaded, and C will use that
65             module rather than the C 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—for example, in Linux you may prefer to call the C
70             system call directly from Perl to avoid L’s XS overhead.
71              
72             =back
73              
74             In scalar contact, C 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
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 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 for portability notes for C
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 6     6   509005 use strict;
  6         57  
  6         177  
95 6     6   32 use warnings;
  6         12  
  6         171  
96              
97 6     6   1340 use Errno ();
  6         4048  
  6         994  
98              
99             our $VERSION = '0.14-TRIAL1';
100              
101             #As light as possible …
102              
103             my $result;
104              
105             sub import {
106 1     1   8 shift;
107              
108 1         505 require "IO/SigGuard/$_.pm" for @_;
109              
110 1         1113 return;
111             }
112              
113             our $AUTOLOAD;
114              
115             sub AUTOLOAD {
116 6     6   18160 $AUTOLOAD = substr( $AUTOLOAD, 1 + rindex($AUTOLOAD, ':') );
117              
118 6         7440 require "IO/SigGuard/$AUTOLOAD.pm";
119              
120 6         90 goto &{ IO::SigGuard->can($AUTOLOAD) };
  6         251  
121             }
122              
123             =head1 REPOSITORY
124              
125             L
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
137              
138             =head1 LICENSE
139              
140             This distribution is released under the same license as Perl.
141              
142             =cut
143              
144             1;