text: - NAME
  - VERSION
  - SYNOPSIS
  - DESCRIPTION
  - FUNCTIONS
  - lock
  - lock_ex
  - $success = Dir::Flock::lock( $directory [, $timeout ] )
  - $success = Dir::Flock::lock_ex( $directory [, $timeout ] )
  - lock_sh
  - $success = Dir::Flock::lock_sh( $directory [, $timeout ] )
  - unlock
  - $success = Dir::Flock::unlock( $directory )
  - getDir
  - $tmp_directory = Dir::Flock::getDir( $root )
  - flock
  - $success = Dir::Flock::flock( $dir, $op )
  - lockobj
  - lockobj_ex
  - $lock = Dir::Flock::lockobj( $dir [, $timeout] );
  - $lock = Dir::Flock::lockobj_ex( $dir [, $timeout] );
  - lockobj_sh
  - my $lock = Dir::Flock::lockobj_sh($dir [, $timeout])
  - sync
  - sync_ex
  - $result = Dir::Flock::sync CODE $dir [, $timeout]
  - @result = Dir::Flock::sync_ex CODE $dir [, $timeout]
  - sync_sh
  - $result = Dir::Flock::sync_sh BLOCK $dir [, $timeout]
  - @result = Dir::Flock::sync_sh BLOCK $dir [, $timeout]
  - EXPORTS
  - VARIABLES
  - LIMITATIONS
  - SUPPORT
  - AUTHOR
  - LICENSE AND COPYRIGHT
  NAME
  Dir::Flock - advisory locking of a dedicated directory
  VERSION
  0.04
  SYNOPSIS
  use Dir::Flock; my $dir = Dir::Flock::getDir("/home/mob/projects/foo"); my $success = Dir::Flock::lock($dir); # ... synchronized code $success = Dir::Flock::unlock($dir); # flock semantics use Fcntl ':flock'; $success = Dir::Flock::flock($dir, LOCK_EX | LOCK_NB); ... Dir::Flock::flock($dir, LOCK_UN); # mutex/scoping semantics { my $lock = Dir::Flock::lockobj($dir); ... synchronized code ... } # lock released when $lock goes out of scope # code ref semantics Dir::Flock::sync { ... synchronized code ... }, $dir
  DESCRIPTION
  Dir::Flock implements advisory locking of a directory. The use case is to execute synchronized code (code that should only be executed by one process or thread at a time) or provide exclusive access to a file or other resource.
  Dir::Flock has more overhead than some of the other synchronization techniques available to Perl programmers, but it might be the only technique that works on NFS (Networked File System).
  Algorithm
  File locking is difficult on NFS because, as I understand it, each node maintains a cache that includes file contents and file metadata. When a system call wants to check whether a lock exists on a file, the filesystem driver might inspect the cached file rather than the file on the server, and it might miss an action taken by another node to lock a file.
  The cache is not used, again, as I understand it, when the filesystem driver reads a directory. If advisory locking is accomplished through reading the contents of a directory, it will not be affected by NFS's caching behavior.
  To acquire a lock in a directory, this module writes a small file into the directory. Then it checks if this new file is the "oldest" file in the directory. If it is the oldest file, then the process has acquired the lock. If there is already an older file in the directory, than that file specifies what process has a lock on the directory, and we have to wait and try again later. To unlock the directory, the module simply deletes the file in the directory that represents its lock.
  Semantics
  This module offers several different semantics for advisory locking of a directory.
  functional semantics
  The core Dir::Flock::lock and Dir::Flock::unlock functions begin and end advisory locking on a directory. All of the other semantics are implemented in terms of these functions.
  $ok = Dir::Flock::lock( "/some/path" ); $ok = Dir::Flock::lock( "/some/path", $timeout ); $ok = Dir::Flock::unlock( "/some/path" );
  flock semantics
  The function Dir::Flock::flock emulates the Perl flock builtin, accepting the same arguments for the operation argument.
  use Fcntl ':flock'; $ok = Dir::Flock::flock( "/some/path", LOCK_EX ); ... $ok = Dir::Flock::flock( "/some/path", LOCK_UN );
  scope-oriented semantics
  The Dir::Flock::lockobj function returns an object representing a directory lock. The lock is released when the object goes out of scope.
  { my $lock = Dir::Flock::lockobj( "/some/path" ); ... } # $lock out of scope, lock released
  BLOCK semantics
  The Dir::Flock::sync accepts a block of code or other code reference, to be executed with an advisory lock on a directory.
  Dir::Flock::sync { ... synchronized code ... } "/some/path";
  System requirements
  The locking algorithm requires a version of Time::HiRes with the
  stat function (namely v1.92 or better, though later versions seem to have some fixes related to the
  stat function). It also requires that the operating system have support for subsecond file timestamps (look for a positive return value from
  &Time::HiRes::d_hires_stat) and filesystem support.
  Version 0.03 of
  Dir::Flock includes the Dir::Flock::Mock package, which implements the
  Dir::Flock API of advisory directory locking in terms of the builtin
  flock.
  Dir::Flock will load and use
  Dir::Flock::Mock on MSWin32 systems and when it is detected that the operating system does not support subseceond file timestamps. The user may also call
  require Dir::Flock::Mock
  in any other context where the requirements to use
  Dir::Flock may not be met.
  FUNCTIONS
  Most functions return a false value and set the package variable
  $Dir::Flock::errstr if they are unsuccessful.
  lock
  lock_ex
  $success = Dir::Flock::lock( $directory [, $timeout ] )
  $success = Dir::Flock::lock_ex( $directory [, $timeout ] )
  Attempts to obtain an exclusive lock on the given directory. While the directory is locked, the
  lock or
  lock_sh call on the same directory from other processes or threads will block until the directory is unlocked (see "unlock"). Returns true if the lock was successfully acquired.
  If an optional
  $timeout argument is provided, the function will try for at least
  $timeout seconds to acquire the lock, and return a false value if it is not successful in that time. Use a timeout of zero to make a "non-blocking" exclusive lock request.
  lock_sh
  $success = Dir::Flock::lock_sh( $directory [, $timeout ] )
  Attempts to obtain a shared lock on the given directory. While there are shared locks on a directory, other calls to
  lock_sh may also receive a shared lock on the directory but calls to
  lock/
  lock_ex on the directory will block until all shared locks are removed.
  If an optional
  $timeout argument is provided, the function will try for at least
  $timeout seconds to acquire the lock, and return a false value if it is not successful in that time. Use a timeout of zero to make a "non-blocking" shared lock request.
  unlock
  $success = Dir::Flock::unlock( $directory )
  Releases the exclusive or shared lock on the given directory held by this process. Returns a false value if the current process did not possess the lock on the directory.
  getDir
  $tmp_directory = Dir::Flock::getDir( $root )
  Creates a temporary and empty directory in a subdirectory of
  $root that is suitable for use as a synchronization directory. The directory will automatically be cleaned up when the process that called this function exits.
  If the input to
  getDir is a filename rather than a directory name, a new subdirectory will be created in the directory where the file is located.
  flock
  $success = Dir::Flock::flock( $dir, $op )
  Acquires and releases advisory locks on the given directory with the same semantics as the Perl builtin flock function.
  lockobj
  lockobj_ex
  $lock = Dir::Flock::lockobj( $dir [, $timeout] );
  $lock = Dir::Flock::lockobj_ex( $dir [, $timeout] );
  Attempts to acquire an exclusive advisory lock for the given directory. On success, returns a handle to the directory lock with the feature that the lock will be released when the handle goes out of scope. This allows you to use this module with syntax such as
  { my $lock = Dir::Flock::lockobj( "/some/path" ); ... synchronized code ... } # $lock out of scope, so directory lock released ... unsynchronized code ...
  Optional
  $timeout argument causes the function to block for a maximum of
  $timeout seconds attempting to acquire the lock. If
  $timeout is not provided or is
  undef, the function will block indefinitely while waiting for the lock.
  Returns a false value and may sets
  $Dir::Flock::errstr if the function times out or is otherwise unable to acquire the directory lock.
  lockobj_ex is an alias for
  lockobj.
  lockobj_sh
  my $lock = Dir::Flock::lockobj_sh($dir [, $timeout])
  Analogue to "lockobj_ex". Returns a reference to a shared lock on a directory that will be released when the reference goes out of scope.
  Returns a false value and may set
  $Dir::Flock::errstr if the function times out or otherwise fails to acquire a shared lock on the directory.
  sync
  sync_ex
  $result = Dir::Flock::sync CODE $dir [, $timeout]
  @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
  $timeout argument will cause the function to give up and return a false value if the lock cannot be acquired after
  $timeout seconds. Callers should be careful to distinguish cases where the specified code reference returns nothing and where the
  sync function times out and returns nothing. One way to distinguish these cases is to check the value of
  $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
  $code produces a fatal error.
  sync_sh
  $result = Dir::Flock::sync_sh BLOCK $dir [, $timeout]
  @result = Dir::Flock::sync_sh BLOCK $dir [, $timeout]
  Analogue of "sync_ex" but executes the code block while there is an advisory shared lock on the given directory.
  EXPORTS
  Nothing is exported from
  Dir::Flock by default, but all of the functions documented here may be exported by name.
  Many of the core functions of
  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.
  VARIABLES
  PAUSE_LENGTH
  $Dir::Flock::PAUSE_LENGTH
  $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.
  LIMITATIONS
  See "System requirements" above.
  The Dir::Flock::Mock module can be loaded when necessary to provide a consistent synchronization API on systems that require
  Dir::Flock to work properly and on systems that don't support
  Dir::Flock.
  SUPPORT
  You can find documentation for this module with the perldoc command.
  perldoc Dir::Flock
  You can also look for information at:
  RT: CPAN's request tracker (report bugs here)
  CPAN Ratings.