view release on metacpan or  search on metacpan

lib/Dir/Flock.pm  view on Meta::CPAN

=head2 $result = Dir::Flock::sync CODE $dir [, $timeout]

=head2 @result = Dir::Flock::sync_ex CODE $dir [, $timeout]

Semantics for executing a block of code while there is an
advisory exclusive lock on the given directory. The code can
be evaluated in both scalar or list contexts. An optional
C<$timeout> argument will cause the function to give up and
return a false value if the lock cannot be acquired after
C<$timeout> seconds. Callers should be careful to distinguish
cases where the specified code reference returns nothing and
where the C<sync> function fails to acquire the lock and returns nothing.
One way to distinguish these cases is to check the value of
C<$Dir::Flock::errstr>, which will generally be set if there
was an issue with the locking mechanics.

The lock is released in the event that the given C<BLOCK>
produces a fatal error.


=head2 sync_sh

=head2 $result = Dir::Flock::sync_sh CODE $dir [, $timeout]

=head2 @result = Dir::Flock::sync_sh CODE $dir [, $timeout]

Analogue of L<"sync_ex"> but executes the code block while
there is an advisory shared lock on the given directory.


=head1 DEPENDENCIES

C<Dir::Flock> requires L<Time::HiRes> where the C<Time::HiRes::time>
function has subsecond resolution.


=head1 EXPORTS

Nothing is exported from C<Dir::Flock> by default, but all of
the functions documented here may be exported by name.

Many of the core functions of C<Dir::Flock> have the same name
as Perl builtin functions or functions from other popular modules,
so users should be wary of importing functions from this module
into their working namespace.



=head1 VARIABLES

=head2 PAUSE_LENGTH

=head2 $Dir::Flock::PAUSE_LENGTH

C<$Dir::Flock::PAUSE_LENGTH> is the average number of seconds that
the module will wait after a failed attempt to acquire a lock before
attempting to acquire it again. The default value is 0.001,
which is a good setting for having a high throughput when the
synchronized operations take a short amount of time. In contexts
where the synchronized operations take a longer time, it may
be appropriate to increase this value to reduce busy-waiting CPU
utilization.

=cut

# also under VARIABLES: HEARTBEAT_CHECK

# =head1 ENVIRONMENT    =>   DIR_FLOCK_DEBUG

# =cut



=head1 LIMITATIONS

C<Dir::Flock> requires that the function values of L<Time::HiRes>
have subsecond resolution


If C<Dir::Flock> is going to be used to synchronize a networked
directory across multiple hosts, it is imporant that the clocks
be synchronized between those hosts. Otherwise, a host with a
"fast" clock will be able to steal locks from a host with a 
"slow" clock.


=head1 SEE ALSO  

Many other modules have taken a shot at advisory locking over
NFS, including L<Mail::Box::Locker::NFS>, L<File::NFSLock>.
L<File::SharedNFSLock>, and L<IPC::ConcurrencyLimit::Lock::NFS>.


=head1 SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc Dir::Flock


You can also look for information at:

=over 4

=item * CPAN Ratings

L<http://cpanratings.perl.org/d/Dir-Flock>

=item * E<lt>mob@cpan.orgE<gt>

With the decommissioning of http://rt.cpan.org/, 
please send bug reports and feature requests
directly to the author's email address.

=back




=head1 AUTHOR