whio  whio_locking

ACHTUNG: AS OF 20110523, THIS PAGE IS NOW MAINTAINED IN THE NEW WIKI: http://whiki.wanderinghorse.net/wikis/whio/?page=whio_locking

See also: whio_dev, whio_epfs

Byte Locking in whio

The whio API includes a class named whio_lock_request which is modeled closely after the struct flock type used by fcntl()-style locking (defined by POSIX). The whio_lock_request class is used in conjunction with whio ioctls (whio_dev_ioctl()) to pass on locking requests to devices. The specifics of the interface are documented in the API docs, but the abstraction API allows for at least the following operations:

  • Set a read-only or read-write lock, either waiting for a lock if necessary or failing if there is a lock contention.
  • Unlocking a lock placed via one of the set operations.
  • Testing whether a given lock would be possible, without actually placing the lock.

The whio_dev implementations which use files as their back-end storage support these locks by transforming them into fcntl()-style locks. (There are two such implementations: one proxies a FILE handle and one proxies a file descriptor.) For this support to be enabled, the compile-time configuration option WHIO_CONFIG_ENABLE_FCNTL (defined in whio_config.h) must be set to a true value.

The whio_dev subdevice class indirectly supports locking by translating the lock coordinates to be relative to the parent device before passing the request on to the parent.

In principal, many types of devices could implement compatible locking semantics, but in practice there is little reason (other than academic) to do so (and doing so would rarely be trivial).

The interface does not (and cannot) define whether lock attempts which are interrupted by an exception are re-tried or fail with an error.

For much more detail about the interface see the header file whio_dev.h and search for WHIO_LOCK.

Example

whio_lock_request lock = whio_lock_request_empty;
lock.type = whio_lock_TYPE_WRITE;
lock.command = whio_lock_CMD_SET_NOWAIT;
lock.start = 10;
lock.length = 100;
int rc = whio_dev_lock( myDevice, &lock );
if( whio_rc.UnsupportedError == rc )
{
    ... myDevice does not support locking;
}
else if( whio_rc.AccessError == rc )
{
    ... probably: myDevice is read-only, but we asked for a write lock;
}
else if( whio_rc.LockingError == rc )
{
    ... lock could not immediately be acquired;
    (we can tell it to wait for the lock using whio_lock_CMD_SET_WAIT)
}
else if( 0 != rc )
{
   ... some other error ...
}

// To unlock it:
lock.type = whio_lock_TYPE_UNLOCK;
rc = whio_dev_lock( myDevice, &lock );