<MvLOCKFILE>

Multiple lock requests with <MvLOCKFILE> on the same file are queued. There is no limit on the number of files on which lock requests can be made. filename can be any file--a database, memo, index, or flat (.dat,.txt, etc.) file. <MvLOCKFILE> tags can be nested.

Miva Script also provides the miva_lockfile() function.

Attributes

• FILE: Required path and filename within the data folder to the file that will be locked.

Locking Files

Note the distinction between a 'program' and a 'process'. The same program (file containing Miva Script code) can be running more than once simultaneously on the same server: Each such instance of a running program is referred to as a 'process'. Often, multiple instance of a program will be 'competing' with other instances of the same program (that is, other processes) for access to the same files.

<MvLOCKFILE> provides a method for the currently running program to indicate to other processes (which could be other running programs, or other instances of the same program) that it has requested exclusive access to a file. It is important to understand that a single <MvLOCKFILE> by itself does not cause the file to be locked: rather, if two processes are using <MvLOCKFILE>, and one process requests a lock, and then the second process requests a lock on the same file, then the second process is prevented from continuing until the first process's lock request is removed. However, if the second process does not issue an <MvLOCKFILE> before attempting to access the file in question, there is nothing to prevent this access from taking place. For this reason, we refer to the action of <MvLOCKFILE> as a lock request, rather than a lock: it is a request to other Miva Script processes that they 'respect' the current process's request for exclusive access. Another way of looking at this is: <MvLOCKFILE> does not interact with any other Miva Script tag, only other <MvLOCKFILE>s.

Even though <MvLOCKFILE> does not provide absolute security against a file being accessed by another process, it is still a useful technique: if you code an application properly <MvLOCKFILE> will provide protection against other instances of the same application accessing a file simultaneously.

Typically you would not have a lock request in place during the entire execution of your program, as this might unnecessarily block other processes from accessing the file in question. You need to identify blocks of code during whose execution it would be desirable to have a lock request in place. Then you surround the blocks of code with <MvLOCKFILE> and </MvLOCKFILE> tags.

Execution of an <MvFUNCTIONRETURN> inside of an <MvLOCKFILE> block releases all locks.

Database Locking

As indicated in the database sections, when you are adding (<MvADD>) or updating (<MvUPDATE>) a database record, Miva automatically prevents the same record from being updated by more than one process at the same time. No other Miva Script process can access a record while it is locked. However, it can not be guaranteed which update or add will occur first.

<MvLOCKFILE> is neither required nor desirable to provide record-level locking when <MvADD> and <MvUPDATE> are used. But, other database operations-<MvPACK>, <MvMAKEINDEX>, and <MvREINDEX>-do not perform automatic locking. You may wish to use <MvLOCKFILE> to provide these tags with added data integrity (you should lock both the database and index files in question); however, since each of these tags tend to be time-consuming, we recommend that you use them 'off-line', thereby avoiding both data integrity issues and excessive resource consumption on your server.

Examples

In this example, the program requests a lock on the text file workers.txt while an <MvEXPORT> is performed.

<MvLOCKFILE FILE="workers.txt">

<MvEXPORT FILE="workers.txt">

</MvLOCKFILE>

If a lock request exists on a file, and another process requests a lock on that file (with <MvLOCKFILE>), then the second lock request is queued until the first lock request is removed. When the lock request is removed, the second process's lock request becomes the 'primary' one. While the second process is waiting, its execution stops; if the process has to wait a long time, this could cause it to time out. Several lock requests can be queued at once.

Semaphore File

Note: <MvLOCKFILE> uses a 'semaphore file' mechanism. The name of the semaphore file is not guaranteed be the same when Miva Script is used on different platforms, or to remain the same in future implementations of Miva Script. For this reason, programs should not be written in a way that relies on the existence of a specific semaphore file name.

Nesting

You can nest two more <MvLOCKFILE>...</MvLOCKFILE> tag pairs if you need to lock two different files at the same time.

<MvLOCKFILE FILE="input.dat">
    <MvLOCKFILE FILE="output.dat">
    ...
    </MvLOCKFILE>

</MvLOCKFILE>

The <MvLOCKFILE> and </MvLOCKFILE> tags are paired: the innermost </MvLOCKFILE> removes the lock request created by the innermost <MvLOCKFILE> (in this example, the lock request on output.dat).

You should take care to avoid the situation known as a "deadly embrace": this occurs when a process makes a lock request on already locked file within the same process. When the second <MvLOCKFILE> is executed, the process stops executing while it waits for the lock request on foo.dat to be removed; however, this will never happen, precisely because the current process, which is also the process that issued the first lock request, is now stopped! The process will wait until it eventually times out.

<MvLOCKFILE FILE="foo.dat">
    <MvLOCKFILE FILE="foo.dat">
    ...
    </MvLOCKFILE>
    ...

</MvLOCKFILE>

If a process terminates without explicitly removing a lock request on a file, it will be removed automatically the next time an <MvLOCKFILE> requests a lock on the same file.