Lockable File Type
This “class” is defined in lockable.h and lockable.c It provides generic locking facilities for files, and ensures that any required metadata is written and (re)read from disc when necessary. In addition to the fs_lockable_lock() routine that takes arguments similar to the flock(2) system call. It also provides an fs_lockable_init() function that is required to be called by the allocation or initialisation routines of classes implementing lockable. There is an fs_lockable_test() macro that can be used to determine what type of lock is currently held.
The fs_lockable_t structure has common file metadata that is to be used by all the hashing functions. For example the old implementation of the fs_mhash type, … now becomes …
This is first implemented in mhash.c and so examples from that file will be used below.
All functions external to mhash.c use the fs_lockable_t type for argument passing and return values. They do not know about the fs_mhash type at all.
The “subclass” int mhash.c is required to make two functions available to the locking machinery, These are used in fs_lockable_init() and fs_lockable_lock() and fs_lockable_sync() to make sure any required header metadata is written to the file when necessary and re-read from the file if it has (possibly) changed.
There are now two versions of the API calls in mhash.c. The get/put/etc. calls acquire and release the lock themselves. The __fs_mhash_*_r() calls assume the lock to be held by the caller. Some examples:
- If only a single operation is necessary it is safe to simply use, e.g. fs_mhash_get(mh, …)
- If multiple operations are necessary, first acquire the lock then use the *_r variants of the calls
- Repeatedly using a non-*_r variant in, for example, a loop is bad for performance especially for write operations
- Unlike flock(2) it is not possible to upgrade/downgrade a lock without explicitly releasing it
- Write operations must use LOCK_EX.
- Read operations must use LOCK_SH.