[libfile-fcntllock-perl] 01/03: Imported Upstream version 0.20
gregor herrmann
gregoa at debian.org
Tue May 27 15:08:50 UTC 2014
This is an automated email from the git hooks/post-receive script.
gregoa pushed a commit to branch master
in repository libfile-fcntllock-perl.
commit 4651359df59b27d1d557d83759ce7231576c86f9
Author: gregor herrmann <gregoa at debian.org>
Date: Tue May 27 17:03:06 2014 +0200
Imported Upstream version 0.20
---
Changes | 3 ++
Inline_build/Inline.pm.in | 19 ++++---
META.yml | 2 +-
Pure_build/Pure.tmpl | 11 ++--
Pure_build/builder.c | 8 +--
lib/File/FcntlLock.pm | 11 ++--
lib/File/FcntlLock.pod | 123 +++++++++++++++++++++++--------------------
lib/File/FcntlLock/Core.pm | 68 ++++++------------------
lib/File/FcntlLock/Errors.pm | 46 ++++++++++++++--
9 files changed, 150 insertions(+), 141 deletions(-)
diff --git a/Changes b/Changes
index 0436713..426f2e3 100644
--- a/Changes
+++ b/Changes
@@ -1,5 +1,8 @@
Revision history for Perl extension File::FcntlLock
+0.20 Tue May 27 2014
+ - Problem on GNU Hurd hopefully fixed and some cosmetic changes.
+
0.19 Tue May 27 2014
- Builds failed on 32-bit systems due to missing CFLAGS derived
from the Perl installation.
diff --git a/Inline_build/Inline.pm.in b/Inline_build/Inline.pm.in
index 7db8e34..421c15e 100644
--- a/Inline_build/Inline.pm.in
+++ b/Inline_build/Inline.pm.in
@@ -223,17 +223,16 @@ EOF
# with the data from the flock structure
sub lock {
- my ( $flock_struct, $fh, $action ) = @_;
+ my ( $self, $fh, $action ) = @_;
- my $buf = pack_flock( $flock_struct );
+ my $buf = $self->pack_flock( );
my $ret = fcntl( $fh, $action, $buf );
if ( $ret ) {
- unpack_flock( $flock_struct, $buf );
- $flock_struct->{ errno } = $flock_struct->{ error } = undef;
+ $self->unpack_flock( $buf );
+ $self->{ errno } = $self->{ error } = undef;
} else {
- $flock_struct->{ errno } = $! + 0;
- $flock_struct->{ error } = get_error( $! + 0 );
+ $self->get_error( $self->{ errno } = $! + 0 );
}
return $ret;
@@ -245,9 +244,9 @@ sub lock {
# binary blob to be passed to fcntl().
sub pack_flock {
- my $fs = shift;
+ my $self = shift;
my @args;
- push @args, $fs->{ $_ } for @member_list;
+ push @args, $self->{ $_ } for @member_list;
return pack $packstr, @args;
}
@@ -257,9 +256,9 @@ sub pack_flock {
# fcntl() into the 'flock_struct'.
sub unpack_flock {
- my ( $fs, $data ) = @_;
+ my ( $self, $data ) = @_;
my @res = unpack $packstr, $data;
- $fs->{ $_ } = shift @res for @member_list;
+ $self->{ $_ } = shift @res for @member_list;
}
diff --git a/META.yml b/META.yml
index 8e2da25..067c74a 100644
--- a/META.yml
+++ b/META.yml
@@ -1,6 +1,6 @@
--- #YAML:1.0
name: File-FcntlLock
-version: 0.19
+version: 0.20
abstract: File locking with L<fcntl(2)>
author:
- Jens Thoms Toerring jt at toerring.de
diff --git a/Pure_build/Pure.tmpl b/Pure_build/Pure.tmpl
index e2952ef..85f1d40 100644
--- a/Pure_build/Pure.tmpl
+++ b/Pure_build/Pure.tmpl
@@ -28,16 +28,15 @@ our $VERSION = File::FcntlLock::Core->VERSION;
# with the data from the flock structure
sub lock {
- my ( $flock_struct, $fh, $action ) = @_;
- my $buf = pack_flock( $flock_struct );
+ my ( $self, $fh, $action ) = @_;
+ my $buf = $self->pack_flock( );
my $ret = fcntl( $fh, $action, $buf );
if ( $ret ) {
- unpack_flock( $flock_struct, $buf );
- $flock_struct->{ errno } = $flock_struct->{ error } = undef;
+ $self->unpack_flock( $buf );
+ $self->{ errno } = $self->{ error } = undef;
} else {
- $flock_struct->{ errno } = $! + 0;
- $flock_struct->{ error } = get_error( $! + 0 );
+ $self->get_error( $self->{ errno } = $! + 0 );
}
return $ret;
diff --git a/Pure_build/builder.c b/Pure_build/builder.c
index 75a1715..383afae 100644
--- a/Pure_build/builder.c
+++ b/Pure_build/builder.c
@@ -151,10 +151,10 @@ main( void )
"# the data from the 'flock_struct' into a binary blob to be\n"
"# passed to fcntl().\n\n"
"sub pack_flock {\n"
- " my $fs = shift;\n"
+ " my $self = shift;\n"
" return pack( '%s',\n", packstr );
for ( i = 0; i < NUM_ELEMS( params ); ++i )
- printf( " $fs->{ %s }%s", params[ i ].name,
+ printf( " $self->{ %s }%s", params[ i ].name,
i == NUM_ELEMS( params ) - 1 ? " " : ",\n" );
printf( ");\n}\n\n\n"
@@ -164,11 +164,11 @@ main( void )
"# the binary blob received from a call of fcntl() into the\n"
"# 'flock_struct'.\n\n"
"sub unpack_flock {\n"
- " my ( $fs, $data ) = @_;\n"
+ " my ( $self, $data ) = @_;\n"
" ( " );
for ( i = 0; i < NUM_ELEMS( params ); ++i )
- printf( "$fs->{ %-8s }%s", params[ i ].name,
+ printf( "$self->{ %-8s }%s", params[ i ].name,
i == NUM_ELEMS( params ) - 1 ? " " : ",\n " );
printf( ") = unpack( '%s', $data );\n}\n", packstr );
diff --git a/lib/File/FcntlLock.pm b/lib/File/FcntlLock.pm
index a017b33..bf48624 100644
--- a/lib/File/FcntlLock.pm
+++ b/lib/File/FcntlLock.pm
@@ -17,7 +17,7 @@ use Carp;
use base qw( File::FcntlLock::Core DynaLoader );
-our $VERSION = '0.19';
+our $VERSION = '0.20';
bootstrap File::FcntlLock $VERSION;
@@ -29,7 +29,7 @@ bootstrap File::FcntlLock $VERSION;
# process holds a lock.
sub lock {
- my ( $flock_struct, $fh, $action ) = @_;
+ my ( $self, $fh, $action ) = @_;
my ( $ret, $err );
# Figure out the file descriptor - we might get a file handle, a
@@ -45,13 +45,12 @@ sub lock {
$action = -1 unless defined $action;
- if ( $ret = C_fcntl_lock( $fd, $action, $flock_struct, $err ) ) {
- $flock_struct->{ errno } = $flock_struct->{ error } = undef;
+ if ( $ret = C_fcntl_lock( $fd, $action, $self, $err ) ) {
+ $self->{ errno } = $self->{ error } = undef;
} elsif ( $err ) {
die "Internal error in File::FcntlLock module detected";
} else {
- $flock_struct->{ errno } = $! + 0;
- $flock_struct->{ error } = get_error( $! + 0 );
+ $self->get_error( $self->{ errno } = $! + 0 );
}
return $ret;
diff --git a/lib/File/FcntlLock.pod b/lib/File/FcntlLock.pod
index a0a2e46..cc51903 100644
--- a/lib/File/FcntlLock.pod
+++ b/lib/File/FcntlLock.pod
@@ -35,7 +35,7 @@ This text also documents the following sub-packages:
=head1 DESCRIPTION
-File locking in Perl is usually done using the L<flock()> function.
+File locking in Perl is usually done using the C<flock> function.
Unfortunately, this only allows locks on whole files and is often
implemented in terms of the L<flock(2)> system function which has
some shortcomings (especially concerning locks on remotely mounted
@@ -46,39 +46,42 @@ this restricts the use of the module to systems that have a L<fcntl(2)>
system call). Before a file (or parts of a file) can be locked, an
object simulating a flock structure, containing information in a
binary format to be passed to L<fcntl(2)> for locking requests, must
-be created and its properties set. Afterwards, by calling the C<lock()>
+be created and its properties set. Afterwards, by calling the L<lock()>
method a lock can be set and removed or it can be determined if and which
process currently holds the lock.
File::FcntlLock (or its alias File::FcntlLock::XS) uses a shared library,
build during installation, to call the L<fcntl(2)> system function directly.
If this is unsuitable there are two alternatives, File::FcntlLock::Pure and
-File::FcntlLock::Inline. Both call the Perl L<fcntl()> function instead and
+File::FcntlLock::Inline. Both call the Perl C<fcntl> function instead and
use Perl code to assemble and disassemble the structure. For this at some
time the (system-dependent) binary layout of the flock structure must
have been determined via a program written in C. The difference between
File::FcntlLock::Pure and File::FcntlLock::Inline is that for the former
this happened when the package is installed while for the latter it is
-done each time the package is loaded (e.g., with the L<use> function).
-Thus, for File::FcntlLock::Inline to work a C compiler must be available.
-There are some minor differences in the functionality and the behaviour
-on passing the method for locking invalid arguments to be described
-below.
+done each time the package is loaded (e.g., with C<use>). Thus, for
+File::FcntlLock::Inline to work a C compiler must be available. There
+are some minor differences in the functionality and the behaviour on
+passing the method for locking invalid arguments to be described below.
=head2 Creating objects
-To create a new object, representing a flock structure, call C<new()>:
+=over 4
+
+=item C<new()>
+
+To create a new object, representing a flock structure, call L<new()>:
$fs = new File::FcntlLock;
The object has a number of properties, reflecting the members of the
-flock structure to be passed to L<fcntl(2)> (more below). Per default
-on object creation the C<l_type> property is set to C<F_RDLCK>,
-C<l_whence> to C<SEEK_SET>, and both C<l_start> and C<l_len> to 0,
+flock structure to be passed to L<fcntl(2)> (see below). Per default
+on object creation the L<l_type> property is set to C<F_RDLCK>,
+L<l_whence> to C<SEEK_SET>, and both L<l_start> and L<l_len> to 0,
i.e., the settings for a read lock on the whole file.
-These defaults can be overruled by passing the C<new()> method a set
+These defaults can be overruled by passing the L<new()> method a set
of key-value pairs to initialize the objects properties, e.g. use
$fs = new File::FcntlLock( l_type => F_WRLCK,
@@ -88,6 +91,8 @@ of key-value pairs to initialize the objects properties, e.g. use
if you intend to obtain a write lock for the first 100 bytes of a file.
+=back
+
=head2 Object properties
@@ -106,8 +111,8 @@ write lock or unlock).
=item C<l_whence()>
-This method sets, when called with an argument, the C<l_whence>
-property of the flock object, determining if the C<l_start> value
+This method sets, when called with an argument, the L<l_whence>
+property of the flock object, determining if the L<l_start> value
is relative to the start of the file, to the current position in
the file or to the end of the file. These values are C<SEEK_SET>,
C<SEEK_CUR> and C<SEEK_END> (also see the man page for L<lseek(2)>).
@@ -116,31 +121,31 @@ returned.
=item C<l_start()>
-Queries or sets the start position (offset) of the lock in the
-file according to the mode selected by the C<l_whence> member.
-See also the man page for L<lseek(2)>.
+Queries or sets the start position (offset) of the lock in the file
+according to the mode selected by the L<l_whence> member. See also
+the man page for L<lseek(2)>.
=item C<l_len()>
-Queries or sets the length of the region (in bytes) in the file
-to be locked. A value of 0 is interpreted to mean a lock (starting
-at C<l_start>) to the end of the file. E.g., a lock obtained
-with C<l_whence> set to C<SEEK_SET> and both C<l_start> and
-L<l_len> set to 0 locks the complete file.
-
-According to SUSv3 negative values for C<l_start> are allowed
-(resulting in a lock ranging from C<l_start+l_len> to
-C<l_start-1>). Unfortunately, not all systems allow negative
-arguments and will return an error when you try to obtain the
-lock, so please read the L<fcntl(2)> man page of the system
+Queries or sets the length of the region (in bytes) in the file to
+be locked. A value of 0 is interpreted to mean a lock, starting at
+C<l_start>, to the end of the file. E.g., a lock obtained with
+L<l_whence> set to C<SEEK_SET> and both L<l_start> and L<l_len> set
+to 0 locks the complete file.
+
+According to SUSv3 support for negative values for L<l_len> are
+permitted, resulting in a lock ranging from C<l_start+l_len> up to
+and including C<l_start-1>. But not all systems support negative
+values for L<l_len> and will return an error when you try to obtain
+such a lock, so please read the L<fcntl(2)> man page of the system
carefully for details.
=item C<l_pid()>
-If a call of the C<lock()> method with C<F_GETLK> indicates that
+If a call of the L<lock()> method with C<F_GETLK> indicates that
another process is holding the lock (in which case the L<l_type>
property will be either C<F_WRLCK> or C<F_RDLCK>) a call of the
-C<l_pid()> method returns the PID of the process holding the lock.
+L<l_pid()> method returns the PID of the process holding the lock.
This method does not accept any arguments.
=back
@@ -149,17 +154,17 @@ This method does not accept any arguments.
After having set up the object representing a flock structure one
can then try to obtain a lock, release it or determine the current
-holder of the lock by invoking the C<lock()> method:
+holder of the lock by invoking the L<lock()> method:
-=over 2
+=over 4
=item C<lock()>
-It expects two arguments. The first one is a file handle (or typeglob).
-File::FcntlLock and thus File::FcntlLock::XS (B<but neither>
-File::FcntlLock::Pure B<nor> File::FcntlLock::Inline) also accepts an
-integer file descriptor. The second is a flag indicating the action to
-be taken, e.g.
+This method expects two arguments. The first one is a file handle
+(or typeglob). File::FcntlLock, and thus File::FcntlLock::XS (B<but
+neither> File::FcntlLock::Pure B<nor> File::FcntlLock::Inline), also
+accepts a "raw" integer file descriptor. The second argument is a
+flag indicating the action to be taken. So call it as in
$fs->lock( $fh, F_SETLK );
@@ -169,11 +174,11 @@ There are three values that can be used as the second argument:
=item C<F_SETLK>
-With C<F_SETLK> the C<lock()> method tries to obtain a lock (when
-C<l_type> is set to either C<F_WRLCK> or C<F_RDLCK>) or releases
-it (if C<l_type> is set to C<F_UNLCK>). If an attempt is made to
-obtain a lock but a lock is already held by some other process the
-method call returns C<undef> and C<errno> is set to C<EACCESS> or
+With C<F_SETLK> the L<lock()> method tries to obtain a lock (when
+L<l_type> is set to either C<F_WRLCK> or C<F_RDLCK>) or releases it
+(if L<l_type> is set to C<F_UNLCK>). If an attempt is made to obtain
+a lock but a lock is already being held by some other process the
+method returns C<undef> and C<errno> is set to C<EACCESS> or
C<EAGAIN> (please see the the man page for L<fcntl(2)> for more
details).
@@ -187,8 +192,8 @@ method returns C<undef> and C<errno> is set to C<EINTR>.
=item C<F_GETLK>
-WithC<F_GETLK> the C<lock()> method determines if and which process
-currently is holding the lock. If there's no other lock the C<l_type>
+With C<F_GETLK> the L<lock()> method determines if and which process
+currently is holding the lock. If there's no other lock the L<l_type>
property will be set to C<F_UNLCK>. Otherwise the flock structure object
is set to the values that would prevent us from obtaining a lock. There
may be several processes that keep us from getting a lock, including
@@ -198,10 +203,12 @@ no control over which process this is.
=back
-On success the C<lock()> method returns the string "0 but true". If
+On success the L<lock()> method returns the string "0 but true",
+i.e., a value that is true in boolean but 0 in numeric context. If
the method fails (as indicated by an C<undef> return value) you can
-either immediately evaluate the error number (using $!, $ERRNO
-or $OS_ERROR) or check for it via the methods discussed below.
+either immediately evaluate the error number (using $!, $ERRNO or
+$OS_ERROR) or check for it via the methods discussed below at some
+later time.
=back
@@ -211,26 +218,26 @@ or $OS_ERROR) or check for it via the methods discussed below.
There are minor differences between File::FcntlLock on the one hand
and File::FcntlLock::Pure and File::FcntlLock::Inline on the other,
due to the first calling the system function L<fcntl(2)> directly
-while the latter two invoke the Perl L<fcntl> function. Perl's
-L<fcnrtl> function already returns a Perl error on some types of
+while the latter two invoke the Perl C<fcntl> function. Perl's
+C<fcntl> function already returns a Perl error on some types of
invalid arguments. In contrast File::FcntlLock passes them on to the
L<fcntl(2)> system call and then returns the systems response to the
caller.
There are three methods for obtaining information about the
-reason the a call of the C<lock()> method failed:
+reason the a call of the L<lock()> method failed:
=over 4
=item C<lock_errno()>
-Returns the C<errno> error number from the latest call of C<lock()>.
+Returns the C<errno> error number from the latest call of L<lock()>.
If the last call did not result in an error C<undef> is returned.
=item C<error()>
Returns a short description of the error that happened during the
-latest call of C<lock()>. Please take the messages with a grain of
+latest call of L<lock()>. Please take the messages with a grain of
salt, they represent what SUSv3 (IEEE 1003.1-2001) and the Linux,
TRUE64, OpenBSD3 and Solaris8 man pages tell what the error numbers
mean. There could be differences (and additional error numbers) on
@@ -238,7 +245,7 @@ other systems. If there was no error the method returns C<undef>.
=item C<system_error()>
-While the C<error()> method tries to return a string with some direct
+While the L<error()> method tries to return a string with some direct
relevance to the locking operation (i.e., "File or segment already
locked by other process(es)" instead of "Permission denied") this method
returns the "normal" system error message associated with C<errno>. The
@@ -269,7 +276,7 @@ call. Note also that under certain circumstances the File::FcntlLock::Pure
and File::FcntlLock::Inline modules may not have been installed. This
happens on 32-bit systems that use 64-bit integers in their flock
structure but where the installed Perl version doesn't support the 'q'
-format for its L<pack()> and L<unpack()> functions.
+format for its C<pack> and C<unpack> functions.
=head1 CREDITS
@@ -278,9 +285,9 @@ Thanks to Mark Jason Dominus and Benjamin Goldberg for helpful discussions,
code examples and encouragement. Glenn Herteg pointed out several problems
and also helped improve the documentation. Julian Moreno Patino helped
correcting the documentation and pointed out problems arising on GNU Hurd
-(which seems to have only very rudimentary support for locking with fcntl(2),
-at least at that time). Niko Tyni and Guillem Jover encouraged and helped
-with implementing alternatives to a XS-only approach which hopefully will
+which seems to have only very rudimentary support for locking with
+L<fcntl(2)>. Niko Tyni and Guillem Jover encouraged and helped with
+implementing alternatives to an XS-only approach which hopefully will
make the module more useful under certain circumstances.
diff --git a/lib/File/FcntlLock/Core.pm b/lib/File/FcntlLock/Core.pm
index c346afc..95f642b 100644
--- a/lib/File/FcntlLock/Core.pm
+++ b/lib/File/FcntlLock/Core.pm
@@ -18,7 +18,7 @@ use Carp;
use base qw( File::FcntlLock::Errors Exporter );
-our $VERSION = '0.19';
+our $VERSION = '0.20';
# Items to export into callers namespace by default.
@@ -29,7 +29,7 @@ our @EXPORT = qw( F_GETLK F_SETLK F_SETLKW
###########################################################
-# Method for creating an object
+# Method for creating the object
sub new {
my $inv = shift;
@@ -69,7 +69,7 @@ sub new {
# Method for setting or querying the 'l_type' property
sub l_type {
- my $flock_struct = shift;
+ my $self = shift;
if ( @_ ) {
my $l_type = shift;
@@ -79,18 +79,17 @@ sub l_type {
carp "Invalid argument in call of l_type method";
return;
}
- $flock_struct->{ l_type } = $l_type;
+ $self->{ l_type } = $l_type;
}
- return $flock_struct->{ l_type };
+ return $self->{ l_type };
}
###########################################################
# Method for setting or querying the 'l_whence' property
-
sub l_whence {
- my $flock_struct = shift;
+ my $self = shift;
if ( @_ ) {
my $l_whence = shift;
@@ -100,75 +99,42 @@ sub l_whence {
carp "Invalid argument in call of l_whence method";
return;
}
- $flock_struct->{ l_whence } = $l_whence;
+ $self->{ l_whence } = $l_whence;
}
- return $flock_struct->{ l_whence };
+ return $self->{ l_whence };
}
###########################################################
-# Method for setting or querying the 'l_start' property
+# Method to set or query of the 'l_start' property
sub l_start {
- my $flock_struct = shift;
+ my $self = shift;
- $flock_struct->{ l_start } = shift if @_;
- return $flock_struct->{ l_start };
+ $self->{ l_start } = shift if @_;
+ return $self->{ l_start };
}
###########################################################
-# Method for setting or querying the 'l_len' property
+# Method to set or query the 'l_len' property
sub l_len {
- my $flock_struct = shift;
+ my $self = shift;
- $flock_struct->{ l_len } = shift if @_;
- return $flock_struct->{ l_len };
+ $self->{ l_len } = shift if @_;
+ return $self->{ l_len };
}
###########################################################
-# Method for querying the 'l_pid' property
+# Method to query the 'l_pid' property
sub l_pid {
return shift->{ l_pid };
}
-###########################################################
-# Method returns the error number from the latest call of the
-# derived classes lock() function. If the last call did not
-# result in an error the method returns undef.
-
-=cut
-
-sub lock_errno {
- return shift->{ errno };
-}
-
-
-###########################################################
-# Method returns a short description of the error that happenend
-# on the latest call of derived classes lock() method with the
-# object. If there was no error the method returns undef.
-
-sub error {
- return shift->{ error };
-}
-
-
-###########################################################
-# Method returns the "normal" system error message associated
-# with errno. The method returns undef if there was no error.
-
-sub system_error {
- local $!;
- my $flock_struct = shift;
- return $flock_struct->{ errno } ? $! = $flock_struct->{ errno } : undef;
-}
-
-
1;
diff --git a/lib/File/FcntlLock/Errors.pm b/lib/File/FcntlLock/Errors.pm
index 00ca69f..c51413c 100644
--- a/lib/File/FcntlLock/Errors.pm
+++ b/lib/File/FcntlLock/Errors.pm
@@ -22,8 +22,8 @@ my %fcntl_error_texts;
BEGIN {
# Set up a hash with the error messages, but only for errno's that Errno
- # knows about. The texts represent what's written in SUSv3 and in the man
- # pages for Linux, TRUE64, OpenBSD3 and Solaris8.
+ # knows about. The texts represent what is written in SUSv3 and in the
+ # man pages for Linux, TRUE64, OpenBSD3 and Solaris8.
my $err;
@@ -85,10 +85,46 @@ BEGIN {
}
+###########################################################
+# Function for converting an errno to a useful, human readable
+# message.
+
sub get_error {
- my $err = shift;
- return defined $fcntl_error_texts{ $err } ? $fcntl_error_texts{ $err }
- : "Unexpected error: $!";
+ my ( $self, $err ) = @_;
+ return $self->{ error } =
+ defined $fcntl_error_texts{ $err } ? $fcntl_error_texts{ $err }
+ : "Unexpected error: $!";
+}
+
+
+###########################################################
+# Method returns the error number from the latest call of the
+# derived classes lock() function. If the last call did not
+# result in an error the method returns undef.
+
+sub lock_errno {
+ return shift->{ errno };
+}
+
+
+###########################################################
+# Method returns a short description of the error that happenend
+# on the latest call of derived classes lock() method with the
+# object. If there was no error the method returns undef.
+
+sub error {
+ return shift->{ error };
+}
+
+
+###########################################################
+# Method returns the "normal" system error message associated
+# with errno. The method returns undef if there was no error.
+
+sub system_error {
+ local $!;
+ my $self = shift;
+ return $self->{ errno } ? $! = $self->{ errno } : undef;
}
--
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/pkg-perl/packages/libfile-fcntllock-perl.git
More information about the Pkg-perl-cvs-commits
mailing list