Advisory Locking

Advisory Locking — advisory locking

Synopsis




#define     SBUILD_LOCK_ERROR
enum        SbuildLockError;
enum        SbuildLockType;
gboolean    sbuild_lock_set_lock            (int fd,
                                             SbuildLockType lock_type,
                                             guint timeout,
                                             GError **error);
gboolean    sbuild_lock_unset_lock          (int fd,
                                             GError **error);

Description

These functions implement simple whole-file shared and exclusive advisory locking based upon POSIX fcntl byte region locks.

Details

SBUILD_LOCK_ERROR

#define SBUILD_LOCK_ERROR sbuild_lock_error_quark()

The error domain for sbuild lock errors.


enum SbuildLockError

typedef enum
{
  SBUILD_LOCK_ERROR_SETUP,
  SBUILD_LOCK_ERROR_TIMEOUT,
  SBUILD_LOCK_ERROR_FAIL
} SbuildLockError;

The errors which can occur while acquiring a lock.

SBUILD_LOCK_ERROR_SETUP An error occured while setting up timeout handling.
SBUILD_LOCK_ERROR_TIMEOUT A timeout occured while waiting on the lock.
SBUILD_LOCK_ERROR_FAIL Lock acquisition failed.

enum SbuildLockType

typedef enum
{
  SBUILD_LOCK_SHARED    = F_RDLCK,
  SBUILD_LOCK_EXCLUSIVE = F_WRLCK,
  SBUILD_LOCK_NONE      = F_UNLCK
} SbuildLockType;

The type of lock. A shared lock may be held simultaneously by many processes, whereas an exclusive lock may only be held by only one process. If a shared lock is already held by another process, a shared lock may be acquired, but not an exclusive lock. If an exclusive lock is held by another process, both shared and exclusive lock acquisition will fail.

SBUILD_LOCK_SHARED A shared (read) lock.
SBUILD_LOCK_EXCLUSIVE An exclusive (write) lock.
SBUILD_LOCK_NONE No lock.

sbuild_lock_set_lock ()

gboolean    sbuild_lock_set_lock            (int fd,
                                             SbuildLockType lock_type,
                                             guint timeout,
                                             GError **error);

Set an advisory lock on a file. A byte region lock is placed on the entire file, regardless of size, using fcntl.

fd : the file descriptor to lock.
lock_type : the type of lock to set.
timeout : the time in seconds to wait for the lock.
error : a GError.
Returns : TRUE on success, FALSE on failure (error will be set to indicate the cause of the failure).

sbuild_lock_unset_lock ()

gboolean    sbuild_lock_unset_lock          (int fd,
                                             GError **error);

Remove an advisory lock on a file. This is equivalent to calling sbuild_lock_set_lock with a lock type of SBUILD_LOCK_NONE and a timeout of 0.

fd : the file descriptor to unlock.
error : a GError.
Returns : TRUE on success, FALSE on failure (error will be set to indicate the cause of the failure).