|
|
|
ctFILMTX
ctFILMTX() is used to request and release a global file mutex.
Declaration
NINT ctFILMTX(pTEXT filename,NINT opcode)
Description
filename is the name of the file to establish the mutex upon.
opcode controls the access to the mutex and its particular properties. File mutexes may be recursive or non-recursive (the default), persistent (default) or non-persistent, created or deleted. The following file mutex opcode options are supported (found in ctport.h):
Opcode |
Value |
Description |
|---|---|---|
ctFILMTXrequest |
1 |
acquire mutex |
ctFILMTXrelease |
2 |
release mutex |
ctFILMTXrecursive |
4 |
recursive request/release |
ctFILMTXcreate |
8 |
create on acquisition if necessary |
ctFILMTXdelete |
16 |
delete file on release |
ctFILMTXnonpersistent |
32 |
mutex will be released when thread terminates, STPUSR(); but the file will not be deleted |
Each call to ctFILMTX() must provide a file name and include either a ctFILMTXrequest or a ctFILMTXrelease option. Other opcode options are OR-ed in with these primary opcode options. If ctFILMTXcreate is included during a request, the file will be created if it does not exist. Without ctFILMTXcreate the request will fail with an error code of FNOP_ERR (12) if the file does not already exist. If the file cannot be created, then the request will return DCRAT_ERR (17). During release, the ctFILMTXdelete option causes the file mutex to be deleted if the mutex is successfully released.
Persistent File Mutexes
By default, a mutex that is acquired is persistent. Persistent means the mutex may exist independent of the thread that acquired the mutex The mutex belongs to the process, not the individual thread. If ctFILMTXnonpersistent is included when the mutex is acquired, then the mutex is assigned to the thread that acquires it, and if the thread does not release the mutex before it calls STPUSR() or CLISAM(), these calls will result in release of the mutex. Only the thread that acquired the non-persistent mutex can release it. If a different thread attempts to release a non-persistent mutex, BOWN_ERR (447) will be returned.
Recursive File Mutexes
ctFILMTXrecursive can be used with both ctFILMTXrequest and ctFILMTXrelease. A recursive mutex can be acquired multiple times by the same process. Each time it is acquired, its recursion count is incremented. Recursive releases each decrement the counter. The release attempt that causes the counter to decrement to zero cause the mutex to be released. If ctFILMTXrelease. is called without including ctFILMTXrecursive then the recursion count is ignored and the mutex is released.
If the same process attempts to acquire a non-recursive mutex that it already owns, then KDUP_ERR (2) will be returned. If a process attempts to acquire a mutex already owned by another process, error NTIM_ERR (156) is returned.
Additional Comments
Because a system lock is acquired on the file, it is generally recommended that a file mutex not contain useful data to be accessed. Instead, we suggest a dummy file. In fact, if the ctFILMTXcreate option causes the file mutex to be created, the file will be empty. The file mutex need not be a c-tree file. c-tree will not read or write to this file, but only acquire a system lock on the file.
The behavior of the file mutex is based on the underlying OS locking protocol. The c-tree logic assumes that if a process locks a local file and another process attempts to lock the same file over a network, the lock will be denied.
Within a single server, use the ctThrdMutex calls to coordinate multiple threads within an application, or use the ctSySQueue() calls to coordinate multiple applications connected to the same server.
