SigGuard.pm

filter: Statementstmt 100% 20 / 20 Branchbran n/a Conditioncond n/a MC/DCmcdc n/a Subroutinesub 100% 5 / 5 Podpod n/a totaltotal 100% 25 / 25 CC 2 SCAR 2.9
CC
2
Cov
100%
import
2.0
BEGIN
1.0
BEGIN
1.0
CRAP 1.3
« SigGuard/recv.pm ↑ Summary
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;
« SigGuard/recv.pm ↑ Summary