safelock.h

#ifndef _SAFELOCK_H
#define _SAFELOCK_H 1
/** \file safelock.h */

/** \mainpage Safelock
 *
 * Safelock is a file-based locking primitive which can provide mutual
 * exclusion between unrelated processes and threads.
 *
 * Safelock offers advantages over POSIX and BSD file locks such as:
 * - Compatible with multi-threaded applications
 * - Support for lock attempt timeouts
 * - Detection of crashed lock holders
 * - Detailed lock status (PID, lock age, custom data)
 *
 * Safelock requires POSIX.1-2008 robust mutexes. Tested under
 * Linux 2.6.32 and Solaris 11.
 *
 * \par Note:
 * A Safelock may need to be recreated after an unexpected kernel crash
 * or power failure. Applications can detect and handle this situation
 * when the ENOTRECOVERABLE error is returned by a Safelock function.
 * This issue can be avoided by placing Safelocks on a tmpfs filesystem,
 * or removing them on boot.
 *
 * \par Example:
 * \code
 * #include "safelock.h"
 * ...
 * safelock_t lock;
 * err = safelock_open(&lock, "lock.dat", 0660);
 * err = safelock_lock(lock, SAFELOCK_LOCK_WAIT, 42);
 * ...
 * err = safelock_unlock(lock);
 * err = safelock_close(&lock);
 * \endcode
 *
 * \author Mark Pulford <mark@kyne.com.au>
 * \par Source:
 * https://github.com/mpx/safelock/
 * \par Documentation:
 * http://mpx.github.com/safelock/
 * \copyright MIT license
 */

#include <stdint.h>
#include <sys/stat.h>
#include <errno.h>

/** Safelock type */
typedef struct _safelock *safelock_t;

/** Alternative lock timeout options. */
enum safelock_timeout_t {
    SAFELOCK_LOCK_WAIT = 0,  /**< Wait until locked. */
    SAFELOCK_LOCK_TRY = 1    /**< Attempt lock once and return
                              * immediately. */
};

/** Updated by safelock_fetch_status() with current Safelock status. */
typedef struct {
    /** Set to 1 when a Safelock is locked.
     *
     * When a Safelock is locked:
     * - Lock metadata is always available (data_valid)
     * - The locking process must still be alive (!crashed) */
    int locked;

    /** Set to 1 if the previous lock owner crashed.
     *
     * When a Safelock owner crashes, the Safelock is automatically
     * unlocked (!locked). */
    int crashed;

    /** Set to 1 when the PID, age and data fields are available.
     *
     * When data_valid is zero, the PID, age and data fields are
     * undefined.
     *
     * Safelock metadata will be unavailable when:
     * - A Safelock has been created and never locked
     * - A Safelock owner crashes during a Safelock update */
    int data_valid;

    pid_t pid;      /**< PID of current or previous Safelock owner. */
    uint64_t age;   /**< Current lock duration (microseconds),
                     * or 0 (unlocked). */
    int data;       /**< Custom data field. */
} safelock_status_t;

/** Print an error message to STDERR and exit.
 *
 * The string representation of any non-zero errno value will be
 * appended to the error message.
 *
 * This helper function is used by Safelock to handle fatal bugs.
 *
 * \param[in]  err  Errno value to decode and append
 * \param[in]  fmt  printf(3) format string
 */
extern void safelock_die(int err, const char *fmt, ...);

/** Open a Safelock.
 *
 * The Safelock file will be created if it does not already exist
 * and mode is non-zero.
 *
 * The lock file must be placed on a local filesystem that supports
 * mmap(2). All processes using a Safelock must have read/write access
 * to the lock file.
 *
 * \param[out]  lock      Safelock to initialise
 * \param[in]   filename  Safelock filename to open/create
 * \param[in]   mode      Permissions to use when creating a new
 *                        lock file
 *
 * \retval  0        Success
 * \retval  EACCESS  Permission denied, or invalid permissions (missing
 *                   owner R/W)
 * \retval  EEXIST   Unable to create a unique Safelock
 * \retval  EINTR    Interrupted by signal
 * \retval  EIO      I/O error updating inode
 * \retval  ENODEV   Underlying filesystem does not support mmap
 * \retval  ENOMEM   Unable to allocate memory for the Safelock
 * \retval  ENOSPC   Disk full
 *
 * May also return any errno values generated by:
 * - open(2)
 * - link(2)
 * - write(2)
 * - unlink(2)
 * - mmap(2)
 */
extern int safelock_open(safelock_t *lock, const char *filename,
                         mode_t mode);

/** Create and open a Safelock with a unique filename.
 *
 * Generates a unique filename by appending 6 random hexidecimal
 * characters.
 *
 * The lock file must be placed on a local filesystem that supports
 * mmap(2). All processes using a Safelock must have read/write access
 * to the lock file.
 *
 * \param[out]  lock         Safelock to initialise
 * \param[in]   file_prefix  Filename prefix
 * \param[in]   mode         Permissions to use for the new lock file
 *
 * \retval  0        Success
 * \retval  EACCESS  Permission denied, or invalid permissions (missing
 *                   owner R/W)
 * \retval  EEXIST   Unable to create a unique Safelock
 *
 * May also return any errno values generated by:
 * - safelock_open()
 */
extern int safelock_open_unique(safelock_t *lock,
                                const char *file_prefix, mode_t mode);

/** Close a Safelock.
 *
 * Automatically unlocks the Safelock if it is locked.
 * Frees system resources related to the Safelock.
 *
 * \param[in,out]  lock  Safelock to close
 *
 * \retval  0                Success
 * \retval  ENOTRECOVERABLE  The Safelock is broken and must be
 *                           recreated before further use.
 */
extern int safelock_close(safelock_t *lock);

/** Lock a Safelock.
 *
 * Atomically updates the custom data field when the lock attempt
 * succeeds.
 *
 * \param[in]  lock     An open Safelock
 * \param[in]  timeout  Timeout (microseconds), SAFELOCK_LOCK_WAIT, or
 *                      SAFELOCK_LOCK_TRY
 * \param[in]  data     Custom data value
 *
 * \retval  0                Success
 * \retval  EBUSY            Safelock already locked (after
 *                           SAFELOCK_LOCK_TRY)
 * \retval  EINVAL           The Safelock has been removed and must be
 *                           re-opened before further use
 * \retval  ENOTRECOVERABLE  The Safelock is broken and must be closed,
 *                           then recreated before further use
 * \retval  ETIMEDOUT        Timeout expired
 */
extern int safelock_lock(safelock_t lock, uint64_t timeout, int data);

/** Open and lock a Safelock.
 *
 * Helper function combining safelock_open() and safelock_lock().
 *
 * The lock file must be placed on a local filesystem that supports
 * mmap(2). All processes using a Safelock must have read/write access
 * to the lock file.
 *
 * \param[out]  lock      Safelock to initialise
 * \param[in]   filename  Safelock filename
 * \param[in]   mode      Permissions to use if the Safelock is created
 * \param[in]   timeout   Timeout (microseconds), SAFELOCK_LOCK_WAIT, or
 *                        SAFELOCK_LOCK_TRY
 * \param[in]   data      Custom data value
 *
 * \retval  0        Success
 * \retval  EACCESS  Permission denied, or invalid permissions (missing
 *                   owner R/W)
 *
 * May also return any errno values generated by:
 * - safelock_open()
 * - safelock_lock()
 */
extern int safelock_lock_file(safelock_t *lock, const char *filename,
                              mode_t mode, uint64_t timeout, int data);

/** Create and lock a Safelock with a unique filename.
 *
 * Helper function combining safelock_open_unique() and safelock_lock().
 *
 * The lock file must be placed on a local filesystem that supports
 * mmap(2). All processes using a Safelock must have read/write access
 * to the lock file.
 *
 * \param[out]  lock         Safelock to initialise
 * \param[in]   file_prefix  Filename prefix
 * \param[in]   mode         Permissions to use for the new lock file
 * \param[in]   data         Custom data value
 *
 * \retval  0        Success
 * \retval  EACCESS  Permission denied, or invalid permissions (missing
 *                   owner R/W)
 *
 * May also return any errno values generated by:
 * - safelock_open_unique()
 * - safelock_lock()
 */
extern int safelock_lock_unique_file(safelock_t *lock,
                                     const char *file_prefix,
                                     mode_t mode, int data);

/** Unlock a Safelock.
 *
 * Only the current owner may unlock a Safelock.
 *
 * \param[in]  lock  Safelock to unlock
 *
 * \retval  0                Success
 * \retval  EINVAL           The Safelock has been removed and must be
 *                           re-opened before further use
 * \retval  ENOTRECOVERABLE  The Safelock is broken and must be closed,
 *                           then recreated before further use
 * \retval  EPERM            Not the current lock owner
 */
extern int safelock_unlock(safelock_t lock);

/** Fetch current status of a Safelock.
 *
 * Atomically fills a safelock_status_t struct with current details for
 * the Safelock.
 *
 * The Safelock will be automatically removed if the Safelock is
 * "locked" and the owner process no longer exists. This may occur if
 * the Safelock is not properly unlocked after a kernel crash or power
 * failure.
 *
 * \param[in]   lock    Safelock to query
 * \param[out]  status  Filled with the current Safelock status
 *
 * \retval  0                Success
 * \retval  EINVAL           The Safelock has been removed and must be
 *                           re-opened before further use
 * \retval  ENOTRECOVERABLE  The Safelock is broken and must be closed,
 *                           then recreated before further use
 */
extern int safelock_fetch_status(safelock_t lock,
                                 safelock_status_t *status);

/** Fetch current status of a Safelock by filename.
 *
 * If the file is missing, an "unlocked" status will be returned
 * instead.
 *
 * \param[in]   filename  Filename of Safelock to query
 * \param[out]  status    Filled with the current Safelock status
 *
 * \retval  0  Success
 *
 * May also return any errno values generated by:
 * - safelock_open() (except ENOENT)
 * - safelock_fetch_status()
 */
extern int safelock_fetch_file_status(const char *filename,
                                      safelock_status_t *status);

/** Return the filename for a Safelock.
 *
 * \param[in]  lock  Safelock
 *
 * \returns
 *
 * A pointer to the filename. The pointer remains valid until the
 * Safelock is closed.
 */
extern char *safelock_filename(safelock_t lock);

/** Atomically update the Safelock custom data field.
 *
 * Only the current owner may update the data field.
 *
 * \param[in]  lock  Safelock to update
 * \param[in]  data  New value for the data field
 *
 * \retval  0                Success
 * \retval  EINVAL           The Safelock has been removed and must be
 *                           re-opened before further use
 * \retval  ENOTRECOVERABLE  The Safelock is broken and must be closed,
 *                           then recreated before further use
 * \retval  EPERM            Not the current lock owner
 */
extern int safelock_update_data(safelock_t lock, int data);

/** Atomically remove a Safelock from the filesystem.
 *
 * Tags the Safelock as "removed" and deletes the file. Any further
 * operations on the Safelock (except safelock_close()) will return
 * EINVAL.
 *
 * \param[in]  lock  Safelock
 *
 * \retval  0                Success, the safelock has been unlinked
 * \retval  ENOTRECOVERABLE  The Safelock is broken and must be closed,
 *                           then recreated before further use
 *
 * May also return any errno values generated by:
 * - unlink(2)
 */
extern int safelock_remove(safelock_t lock);

/* vi:ai et sw=4 ts=4:
 */

#endif