SDT-base         Contents     Functions         Previous Next     PDF Index

fjlock

Purpose

File lock handling object.

Syntax

ob=fjlock(fname); % initialize object
ob.lock(flag); % lock/unlock with flag
state=ob.locked; % lock status

Description

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

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

.delete[,.close]

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.

.file

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

.lock(flag)

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).
status=obj.lock(flag).

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

.lockWait(fname,flag,icmax,dt)

This functionality implements a file lock strategy with a wait loop for robustness. In practice, the user can call this command to implement a one-liner lock procedure that will hold until lock is successful or fail after a timeout. Syntax is [ob,id]=fjlock.lockWait(fname,flag,icmax,dt) with

The total acceptable delay is thus given by icmax*dt.

Output ob is the fjlock object that will be needed to call for a release with ob.lock(0). Output id is the success flag, possible values are

.locked

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.
status=obj.locked;

.setFile

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.
obj.file=fname;

.setUseNIO(flag)

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.

.tmpFile

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

Examples

% 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


©1991-2024 by SDTools
Previous Up Next