whio  Artifact Content

Artifact 728981865ae4cf282018214ef9622225defe599c:

Wiki page [whio_locking] by stephan 2011-05-23 18:50:57.
D 2011-05-23T18:50:57.685
L whio_locking
P a424e51a521e696a4e21bc163c893f403ab3245d
U stephan
W 2817
<strong>ACHTUNG: AS OF 20110523, THIS PAGE IS NOW MAINTAINED IN THE NEW WIKI:</strong> [http://whiki.wanderinghorse.net/wikis/whio/?page=whio_locking]


See also: [whio_dev], [whio_epfs]

<h1>Byte Locking in whio</h1>

The whio API includes a class named <tt>whio_lock_request</tt> which is modeled closely after the <tt>struct flock</tt> type used by <tt>fcntl()</tt>-style locking (defined by POSIX). The <tt>whio_lock_request</tt> class is used in conjunction with whio ioctls (<tt>whio_dev_ioctl()</tt>) 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 <em>would</em> 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 <tt>fcntl()</tt>-style locks. (There are two such implementations: one proxies a <tt>FILE</tt> handle and one proxies a file descriptor.) For this support to be enabled, the compile-time configuration option <tt>WHIO_CONFIG_ENABLE_FCNTL</tt> (defined in <tt>whio_config.h</tt>) 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 <em>could</em> 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 <tt>whio_dev.h</tt> and search for <tt>WHIO_LOCK</tt>.

<h2>Example</h2>

<verbatim>
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 );
</verbatim>

Z aa10737893d6d92a6c81ff9344bb5bda