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..43ddde31ca31343f32e53f961124cd8e41148720 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.
+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,

[Robert Sesek, 2015/03/12 15:28:03]

Are files normally exclusive on Windows? Do we want most files opened as
sharable if so?

[scottmg, 2015/03/19 22:06:19]

I don't think there's an expected default. I just made them exclusive to start
with so that it'd be clear when something required sharing.

+//! see LoggingLockFile() and LoggingUnlockFile() to control concurrent access.
 //!
 //! \return The newly opened FileHandle, or an invalid FileHandle on failure.
 //!
@@ -193,6 +203,27 @@ FileHandle LoggingOpenFileForWrite(const base::FilePath& path,
                                    FileWriteMode write_mode,
                                    FilePermissions permissions);
 
+//! \brief Locks the given \a file similar to `flock`.
+//!
+//! 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.
+//!
+//! \param[in] file The open file handle to be locked.
+//! \param[in] locking Controls whether the lock is shared (generally for
+//!     multiple readers) or exclusive (generally for a single writer).
+//!
+//! \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.
+//!
+//! \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.
 //!