git/Documentation/technical/api-lockfile.txt, branch v2.3.4

fdopen_lock_file(): access a lockfile using stdio

2014-10-01T21:08:10Z

Add a new function, fdopen_lock_file(), which returns a FILE pointer open to the lockfile. If a stream is open on a lock_file object, it is closed using fclose() on commit, rollback, or close_lock_file(). This change will allow callers to use stdio to write to a lockfile without having to muck around in the internal representation of the lock_file object (callers will be rewritten in upcoming commits). Signed-off-by: Michael Haggerty Signed-off-by: Junio C Hamano

get_locked_file_path(): new function

2014-10-01T20:53:54Z

Add a function to return the path of the file that is locked by a lock_file object. This reduces the knowledge that callers have to have about the lock_file layout. Suggested-by: Ronnie Sahlberg Signed-off-by: Michael Haggerty Signed-off-by: Junio C Hamano

lockfile: rename LOCK_NODEREF to LOCK_NO_DEREF

2014-10-01T20:53:28Z

This makes it harder to misread the name as LOCK_NODE_REF. Suggested-by: Torsten Bögershausen Signed-off-by: Michael Haggerty Signed-off-by: Junio C Hamano

commit_lock_file_to(): refactor a helper out of commit_lock_file()

2014-10-01T20:52:06Z

commit_locked_index(), when writing to an alternate index file, duplicates (poorly) the code in commit_lock_file(). And anyway, it shouldn't have to know so much about the internal workings of lockfile objects. So extract a new function commit_lock_file_to() that does the work common to the two functions, and call it from both commit_lock_file() and commit_locked_index(). Signed-off-by: Michael Haggerty Signed-off-by: Junio C Hamano

api-lockfile: document edge cases

2014-10-01T20:45:14Z

* Document the behavior of commit_lock_file() when it fails, namely that it rolls back the lock_file object and sets errno appropriately. * Document the behavior of rollback_lock_file() when called for a lock_file object that has already been committed or rolled back, namely that it is a NOOP. Signed-off-by: Michael Haggerty Signed-off-by: Junio C Hamano

close_lock_file(): if close fails, roll back

2014-10-01T20:45:13Z

If closing an open lockfile fails, then we cannot be sure of the contents of the lockfile, so there is nothing sensible to do but delete it. This change also insures that the lock_file object is left in a defined state in this error path (namely, unlocked). The only caller that is ultimately affected by this change is try_merge_strategy() -> write_locked_index(), which can call close_lock_file() via various execution paths. This caller uses a static lock_file object which previously could have been reused after a failed close_lock_file() even though it was still in locked state. This change causes the lock_file object to be unlocked on failure, thus fixing this error-handling path. Signed-off-by: Michael Haggerty Signed-off-by: Junio C Hamano

commit_lock_file(): die() if called for unlocked lockfile object

2014-10-01T20:45:13Z

It was previously a bug to call commit_lock_file() with a lock_file object that was not active (an illegal access would happen within the function). It was presumably never done, but this would be an easy programming error to overlook. So before continuing, do a consistency check that the lock_file object really is locked. Helped-by: Johannes Sixt Signed-off-by: Michael Haggerty Signed-off-by: Junio C Hamano

api-lockfile: revise and expand the documentation

2014-10-01T20:38:38Z

Document a couple more functions and the flags argument as used by hold_lock_file_for_update() and hold_lock_file_for_append(). Reorganize the document to make it more accessible. Helped-by: Jonathan Nieder Helped-by: Junio Hamano Signed-off-by: Michael Haggerty Signed-off-by: Junio C Hamano

close_lock_file(): new function in the lockfile API

2008-01-16T23:35:03Z

The lockfile API is a handy way to obtain a file that is cleaned up if you die(). But sometimes you would need this sequence to work: 1. hold_lock_file_for_update() to get a file descriptor for writing; 2. write the contents out, without being able to decide if the results should be committed or rolled back; 3. do something else that makes the decision --- and this "something else" needs the lockfile not to have an open file descriptor for writing (e.g. Windows do not want a open file to be renamed); 4. call commit_lock_file() or rollback_lock_file() as appropriately. This adds close_lock_file() you can call between step 2 and 3 in the above sequence. Signed-off-by: Junio C Hamano

Document lockfile API

2008-01-16T20:42:37Z

We have nice set of placeholders, but nobody stepped in to fill the gap in the API documentation, so I am doing it myself. Signed-off-by: Junio C Hamano