|
The purpose of this module is to provide a robust
and full featured implementation of the
FTP/network locking technology outlined by Sean Burke in his June 1, Sys Admin magazine/ Perl Journal Article on Resource Locking over Networks. For those who do not yet have access to the article, it does locking 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. I am looking for comments on namespace and any
other aspect of the project on which a
reader would care to provide feedback. This work is going on with Mr. Burke's knowledge and approval although he has not reviewed the actual module yet. This is at an alpha/beta stage and the interface is subject to change. Information on the interface is included below from the POD/perldoc. 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; } Methods
new (constructor method) Create a new LockFile::NetLock object. See 'Named Parameters to new' and 'Ordered Parameters to new' for initialization options. Currently just constructs a blessed hash and has no cause for failure.
lock
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.
unlock
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).
errstr
Return string describing last error on LockFile::NetLock object or class. Named Parameters (to new, lock and in some cases
unlock).
-dir 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.
-disconnect
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.
-ftp_heartbeat
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.
-heartbeat
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.
-host
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. -password The password allowing the FTP user to connect to the FTP host. May be inferred from ..netrc if not passed as parameter.
-sleep
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.
-timeout
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.
-user
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. |
