Add Locking calls to file_io.h plus implementations and test

util/file/file_io.h

Index: util/file/file_io.h
diff --git a/util/file/file_io.h b/util/file/file_io.h
index 268bfd3b026ca4c000933f62d2ab88c269b26ae6..b63116ce9649319bf793f319b67b5dde63096421 100644
--- a/util/file/file_io.h
+++ b/util/file/file_io.h
@@ -78,6 +78,15 @@ enum class FilePermissions : bool {
   kWorldReadable,
 };
 
+//! \brief Determines the locking mode that LoggingLockFile uses.

[Mark Mentovai, 2015/03/20 15:03:55]

Nit: parentheses on function names. flock() below, too.

[scottmg, 2015/03/20 21:07:34]

Done.

+enum class FileLocking : bool {
+  //! \brief Equivalent to `flock` with `LOCK_SH`.
+  kShared,
+
+  //! \brief Equivalent to `flock` with `LOCK_EX`.
+  kExclusive,
+};
+
 //! \brief Reads from a file, retrying when interrupted on POSIX or following a
 //!     short read.
 //!
@@ -182,7 +191,8 @@ FileHandle LoggingOpenFileForRead(const base::FilePath& path);
 //! \a write_mode determines the style (truncate, reuse, etc.) that is used to
 //! open the file. On POSIX, \a permissions determines the value that is passed
 //! as `mode` to `open()`. On Windows, the file is always opened in binary mode
-//! (that is, no CRLF translation).
+//! (that is, no CRLF translation). On Windows, the file is opened for sharing,
+//! see LoggingLockFile() and LoggingUnlockFile() to control concurrent access.
 //!
 //! \return The newly opened FileHandle, or an invalid FileHandle on failure.
 //!
@@ -193,6 +203,32 @@ FileHandle LoggingOpenFileForWrite(const base::FilePath& path,
                                    FileWriteMode write_mode,
                                    FilePermissions permissions);
 
+//! \brief Locks the given \a file similar to `fcntl` `F_SETLKW`.

[Mark Mentovai, 2015/03/20 15:03:55]

If we’re going back to flock(), don’t forget to update this.

[scottmg, 2015/03/20 21:07:34]

Done.

+//!
+//! It is an error to attempt to lock a file in a different mode when it is
+//! already locked. This call will block until the lock is acquired. The
+//! entire file is locked.
+//!
+//! If the file is \a locking is FileLocking::kShared, \a file must have been

[Mark Mentovai, 2015/03/20 15:03:55]

Too many “is”?

[scottmg, 2015/03/20 21:07:34]

Done.

+//! opened for reading, and if it's FileLocking::kExclusive, \a file must have
+//! been opened for writing.
+//!
+//! \param[in] file The open file handle to be locked.
+//! \param[in] locking Controls whether the lock is shared reader lock, or an

[Mark Mentovai, 2015/03/20 15:03:54]

is _a_ shared?

[scottmg, 2015/03/20 21:07:34]

Done.

+//!     exclusive writer lock.
+//!
+//! \return `true` on success, or `false` and a message will be logged.
+bool LoggingLockFile(FileHandle file, FileLocking locking);
+
+//! \brief Unlocks a file previously locked with LoggingLockFile().
+//!
+//! It is an error to attempt to unlock a file that was not previously locked.

[Mark Mentovai, 2015/03/20 15:03:54]

If it’s true on Windows too, you can say that closing FileHandle will release
the lock without calling this function. In that case, also add a test to make
sure that this works correctly.

If that’s not true on Windows, say that this function must be called and that
it’s not sufficient to close the FileHandle to get the lock released.

[scottmg, 2015/03/20 21:07:34]

Unfortunately, it's semi-true on Windows.

"""If a process terminates with a portion of a file locked or closes a file that
has outstanding locks, the locks are unlocked by the operating system. However,
the time it takes for the operating system to unlock these locks depends upon
available system resources."""

So, updated to say that it should be released explicitly.

+//!
+//! \param[in] file The open locked file handle to be unlocked.
+//!
+//! \return `true` on success, or `false` and a message will be logged.
+bool LoggingUnlockFile(FileHandle file);
+
 //! \brief Wraps `lseek()` or `SetFilePointerEx()`. Logs an error if the
 //!     operation fails.
 //!