NAME

LockFile::NetLock - FTP based locking using the FTP mkdir command.

SYNOPSIS

  use LockFile::NetLock;

  my $locker = new LockFile::NetLock(
      'ftp.myhost.com', 'lockdir.lck', 'ftpuser', 'ftppassword'
  );
  if ($locker->lock()) {
      # do work requiring lock
      $locker->unlock() ||
          print STDERR $locker->errstr;
  }
  else {
      print STDERR $locker->errstr;
  }            

  -- OR --

  use LockFile::NetLock qw(lock unlock);

  if (lock qw(ftp.myhost.com lockdir.lck ftpuser ftppassword)) {
      # do work requiring lock
      unlock(qw(ftp.myhost.com lockdir.lck)) ||
          print STDERR $LockFile::NetLock::errstr;
  }
  else {
      print STDERR $LockFile::NetLock::errstr;
  }

  -- OR even with a .netrc file --

  use LockFile::NetLock qw(lock unlock);

  if (lock qw(ftp.myhost.com lockdir.lck )) {
      # do work requiring lock
      unlock(qw(ftp.myhost.com lockdir.lck)) ||
          print STDERR $LockFile::NetLock::errstr;
  }
  else {
      print STDERR $LockFile::NetLock::errstr;
  }

DESCRIPTION

Provide locking/mutex mechanism under (at least) UNIX and Win32 that will function correctly even in networked/NFS environments. It is based on the concept that if two processes each connect to the same host via ftp and try to create the same directory that does not yet exist then one will create the directory and the other will be notified that it cannot create the directory because it already exists. The basic ideas are explained in more detail in an article in the summer 2002 Perl journal by Sean M. Burke.

As demonstrated in the SYNOPSIS the module has two interfaces: an object oriented interface and a more traditional subroutine interface. The four most critical parameters, the host name, directory, ftp user and password may be passed unnamed as a list or named with the respective labels -host, -dir, -user, -password. There are also several optional parameters that control the timing of lock events including a total timeout parameter, a sleep time between attempts to create the directory, and a heartbeat option controlling the frequency of verifying the running or dead status of the process that requested the lock. The options and parameters are discussed in an itemized format in the parameters sections below.

It is strongly recommended that users of this module upgrade their Net::FTP module to at least version 2.64. Earlier versions may make errors in removing a lock undetectable.

Methods

constructor $lock = LockFile::NetLock->new( option1 => val1, ... )

Create a new LockFile::NetLock object. See 'Named Parameters to new' and 'Ordered Parameters' for initialization options. Currently just constructs a blessed hash and has no cause for failure.

method $lock->lock() or lock(... intialization parameters ...)

Attempt to acquire the lock by opening an FTP session to an FTP host and creating a directory. Needs no parameters if called using a properly constructed LockFile::NetLock object reference but may be called with all parameters that would otherwise be passed to new for a more traditional subroutine interface. In the case of the subroutine interface lock will return a reference to the newly created lock object but unlock may be called with either the object reference or the host and directory name that will be used internally to uniquely identify the lock object. Returns object reference on success and undef on failure in which case both $LockFile::NetLock::errstr and the object's error field are set.

method $lock->unlock() or unlock($host, $dir)

Release lock by removing directory at FTP host that was created to do locking. Needs no parameters if called using a properly constructed LockFile::NetLock object but can also be called with the FTP host and directory if the lock was created using the "sub" interface to lock described above. Returns 1 on success and undef if there was an error releasing the lock (and this is possible).

method $lock->errstr()

Return string describing last error on LockFile::NetLock object or class.

Named Parameters (to new, lock and in some cases unlock).

option -dir => dirname,

Path of directory that will be created at FTP host. Once the directory is created other processes attempting to create the same directory at the same host will be informed that they cannot do so because the directory already exists. This provides a mutual exclusion effect. Defaults to 'lockdir'. The FTP host and lock directory uniquely identify a lock not otherwise identifiable through an object reference.

option -disconnect => 1,

The module calls a program to create the lock directory and by default the program maintains an FTP connection to the host as long as the lock is held. This option instructs the program to disconnect from the FTP host after creating the lock directory and re-connect later when the lock is released and the directory needs to be removed. This option is included for cases where locks need to be held for a long time and the number of available FTP sessions is limited.

option -ftp_heartbeat => seconds,

Frequency with which action on FTP connection will be taken to prevent FTP idle timeout. Should rarely need to be changed from default of 15 seconds.

option -heartbeat => seconds,

The module calls a program to create the lock directory. If the program that called this module dies or calls unlock then the lock directory must be removed. The heartbeat option sets the frequency in seconds with which the lock program checks the calling program to see if it needs to release the lock. Set to small number for briefly held frequent locks. For long held locks a conservative setting would be 1 second for every 7 minutes the lock is held. Defaults to 2 seconds.

option -host => hostname,

The FTP host on which the lock directory will be created. The FTP host and lock directory uniquely identify a lock not otherwise identifiable through an object reference.

option -password => password,

The password allowing the FTP user to connect to the FTP host. May be inferred from .netrc if not passed as parameter.

option -sleep => seconds,

The amount of time in seconds that the locking process will sleep after a failed attempt to create the lock directory and before trying to create the directory again. Defaults to 4 seconds.

option -timeout => seconds,

The total amount of time in seconds the locking process can spend trying to create the lock directory. If the directory cannot be created before the timeout elapses an error is returned indicating a timeout. Defaults to 40 seconds. Use infinite or forever if you never want to time out.

option -user => username,

FTP login user for the FTP host at which the module will try to create the lock directory. May be inferred from .netrc if not passed as parameter.

Ordered parameters

Until a named parameter is detected by new, lock or unlock, the first four parameters to these functions will be interpreted as -host, -dir, -login and -password respectively.

COPYRIGHT

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

CREDITS

Sean M. Burke sburke@cpan.org - designer and architect of this concept.

Ronald Schmidt RonaldWS@software-path.com - implementor.