Re: [PATCH v4 09/32] lockfile.c: document the various states of lock_file objects

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



Reviewed-by: Ronnie Sahlberg <sahlberg@xxxxxxxxxx>

On Sat, Sep 6, 2014 at 12:50 AM, Michael Haggerty <mhagger@xxxxxxxxxxxx> wrote:
> Document the valid states of lock_file objects, how they get into each
> state, and how the state is encoded in the object's fields.
>
> Signed-off-by: Michael Haggerty <mhagger@xxxxxxxxxxxx>
> ---
>  lockfile.c | 52 ++++++++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 52 insertions(+)
>
> diff --git a/lockfile.c b/lockfile.c
> index 00c972c..964b3fc 100644
> --- a/lockfile.c
> +++ b/lockfile.c
> @@ -4,6 +4,58 @@
>  #include "cache.h"
>  #include "sigchain.h"
>
> +/*
> + * File write-locks as used by Git.
> + *
> + * When a file at $FILENAME needs to be written, it is done as
> + * follows:
> + *
> + * 1. Obtain a lock on the file by creating a lockfile at path
> + *    $FILENAME.lock.  The file is opened for read/write using O_CREAT
> + *    and O_EXCL mode to ensure that it doesn't already exist.  Such a
> + *    lock file is respected by writers *but not by readers*.
> + *
> + *    Usually, if $FILENAME is a symlink, then it is resolved, and the
> + *    file ultimately pointed to is the one that is locked and later
> + *    replaced.  However, if LOCK_NODEREF is used, then $FILENAME
> + *    itself is locked and later replaced, even if it is a symlink.
> + *
> + * 2. Write the new file contents to the lockfile.
> + *
> + * 3. Move the lockfile to its final destination using rename(2).
> + *
> + * Instead of (3), the change can be rolled back by deleting lockfile.
> + *
> + * This module keeps track of all locked files in lock_file_list.
> + * When the first file is locked, it registers an atexit(3) handler;
> + * when the program exits, the handler rolls back any files that have
> + * been locked but were never committed or rolled back.
> + *
> + * A lock_file object can be in several states:
> + *
> + * - Uninitialized.  In this state the object's on_list field must be
> + *   zero but the rest of its contents need not be initialized.  As
> + *   soon as the object is used in any way, it is irrevocably
> + *   registered in the lock_file_list, and on_list is set.
> + *
> + * - Locked, lockfile open (after hold_lock_file_for_update(),
> + *   hold_lock_file_for_append(), or reopen_lock_file()). In this
> + *   state, the lockfile exists, filename holds the filename of the
> + *   lockfile, fd holds a file descriptor open for writing to the
> + *   lockfile, and owner holds the PID of the process that locked the
> + *   file.
> + *
> + * - Locked, lockfile closed (after close_lock_file()).  Same as the
> + *   previous state, except that the lockfile is closed and fd is -1.
> + *
> + * - Unlocked (after commit_lock_file(), rollback_lock_file(), or a
> + *   failed attempt to lock).  In this state, filename[0] == '\0' and
> + *   fd is -1.  The object is left registered in the lock_file_list,
> + *   and on_list is set.
> + *
> + * See Documentation/api-lockfile.txt for more information.
> + */
> +
>  static struct lock_file *lock_file_list;
>
>  static void remove_lock_file(void)
> --
> 2.1.0
>
> --
> To unsubscribe from this list: send the line "unsubscribe git" in
> the body of a message to majordomo@xxxxxxxxxxxxxxx
> More majordomo info at  http://vger.kernel.org/majordomo-info.html
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at  http://vger.kernel.org/majordomo-info.html




[Index of Archives]     [Linux Kernel Development]     [Gcc Help]     [IETF Annouce]     [DCCP]     [Netdev]     [Networking]     [Security]     [V4L]     [Bugtraq]     [Yosemite]     [MIPS Linux]     [ARM Linux]     [Linux Security]     [Linux RAID]     [Linux SCSI]     [Fedora Users]