|Contents   Functions      PDF Index|
File lock handling object.
ob=fjlock(fname); % initialize object ob.lock(flag); % lock/unlock with flag state=ob.locked; % lock status
To avoid simultaneous file access or to help with keeping track of currently processed files, one can use fjlock to test file accessibility or to lock file accessibility to other processes.
fjlock behavior follows the following semantics
The lock is handled within the object, ensuring exclusivity even if several fjlock objects referring to the same file exist in different processes. The lock holder is thus a unique object independently from MATLAB sessions or processes. This leads to three distinct lock statuses:
When a lock holder fjlock is destroyed, the lock is released.
fjlock inherits the handle class, so that any copy refers to the same object (thus same lock status, holder, or destroyed). It is also recommended to use delete instead of clear to destroy the object. The clear command may postpone destruction and thus lock release in recent MATLAB versions.
File locking is never absolutely perfect, as OSes do not use transactional file systems. Besides, POSIX semantics are nowadays weakly enforced to optimize latency, especially over network access, and efficient strategies will depend on the OS. Several lock strategies are thus implemented with their own pros and cons.
To be robust to the possibility of several lock strategies used at once, strategy 2 overrides strategy 1 in the lock holder only, and the lock status is independent from the strategy employed. It is then impossible to lock a file if any lock is detected. One can switch in the lock holder from strategy 1 to 2 but not the other way around until the lock is released. Although very improbable, the lock hold could be lost during the switch. It is anyways recommended not to mix strategies within a given distributed procedure.
The default behavior assumes that to be locked, a file must exist. If a file gets deleted, any referred hold lock will be released. It is however sometimes interesting to place a lock on a non-existing file to protect its creation. This specific behavior only works with the external lock files strategies. The operation must then be explicitly called using flag=3. In such case the external lock file strategy is forced and a lock can be hold on a non-existing file.
fjlock constructor. Calling fjlock will create a new fjlock object. One can provide a file name string fname, and a lock flag integrer on-the-fly.
ob1=fjlock; % create empty object ob1=fjlock(fname); % refer to file fname, access tested ob1=fjlock(fname,flag); % refer to file fname and try to lock with flag
fjlock destruction (and callback). Releases the lock if the object is a lock holder prior to destruction. If no process refers to the object or when exiting MATLAB this method will be called too.
Provide a reference file name. It is possible to change the file reference in an existing object, in such case, the hold locks will be released.
ob1.file=fname2; % change fname
Try to assign a lock flag to the referred file, and outputs the lock status. If the flag is set to false and hold lock is released, otherwise flag defines the lock strategy (and not the lock status per se).
If the file is locked externally (status set to 1), nothing will be performed, one can however try to lock in a wait loop until the lock hold (status 2) is obtained.
Depending on the initial lock status, flag setting will have the following effect
Dynamically provides the object lock status associated to the referred file. Every call to .locked thus tests again file accessibility. The output is then the lock status.
Change the referred file in the object. If the object is a lock holder, the lock is released. No lock is performed on the newly referred file.
Change the external file lock implementation strategy. If flag is false, the IO strategy will be used, the NIO otherwise. It is recommended to stick with the IO strategy.
Generate a temporary file using java IO or NIO method. This method is used internally but can also be called externally to generate an empty temporary file with the methods available in Java. This is a variant to nas2up('tempname'), the difference being that .tmpFile directly creates an empty file.
f1=char(tmpFile(fjlock,sdtdef('tempdir'),'.mat')); % in tempdir with suffix .mat f1=char(tmpFile(fjlock,sdtdef('tempdir'))); % in tempdir no suffix f1=char(tmpFile(fjlock)); % in pwd, no suffix
% fjlock calls example % Generate a file for illustration f1=char(tmpFile(fjlock,sdtdef('tempdir'),'.mat')); % Initialize object ob=fjlock(f1) % dislays .file and .locked status=ob.locked % 0: unlocked % lock the file status=ob.lock(1) % status is 2 exist([f1 '.fjlock'],'file') % no external file status=ob.lock(2) % status remains2 exist([f1 '.fjlock'],'file') % external file exists % unlock the file ob.lock(0) % status is 0 exist([f1 '.fjlock'],'file') % external file has been removed % Now try with two objects ob1=fjlock(f1) % new lock object status2=ob1.lock(2) % status2 is 2 ob1 is lock holder status=ob.locked % status passed to 1 file locked but not by ob status=ob.lock(0) % status sill to 1 does nothing as ob is not holder delete(ob1) % lock release when destructed status=ob.locked % status passed to 0 as no lock exists anymore f1=nas2up('tempname.mat'); ob=fjlock(f1,2); status=ob.locked % 0: file does not exist ob1=fjlock(f1,3); status1=ob1.locked % 2: lock hold on non existing file status=ob.locked % 1: external lock found ob1.lock(0) % 0: lock released