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 times out 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<$code>
produces a fatal error.


=head2 sync_sh

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

=head2 @result = Dir::Flock::sync_sh BLOCK $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 subsection 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

See L<"System requirements"> above.

The L<Dir::Flock::Mock> module can be loaded when necessary
to provide a consistent synchronization API on systems that
require C<Dir::Flock> to work properly and on systems that
don't support C<Dir::Flock>.

=cut

# =head1 SEE ALSO  L<Mail::Box::Locker::NFS>, L<File::NFSLock>.
#        L<File::SharedNFSLock>, 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

Marty O'Brien, E<lt>mob@cpan.orgE<gt>