path: root/Documentation/technical/api-lockfile.txt
AgeCommit message (Collapse)Author
2015-08-10lockfile: move documentation to lockfile.h and lockfile.cMichael Haggerty
Rearrange/rewrite it somewhat to fit its new environment. Signed-off-by: Michael Haggerty <> Signed-off-by: Junio C Hamano <>
2014-10-01fdopen_lock_file(): access a lockfile using stdioMichael Haggerty
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 <>
2014-10-01get_locked_file_path(): new functionMichael Haggerty
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 <>
2014-10-01lockfile: rename LOCK_NODEREF to LOCK_NO_DEREFMichael Haggerty
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 <>
2014-10-01commit_lock_file_to(): refactor a helper out of commit_lock_file()Michael Haggerty
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 <>
2014-10-01api-lockfile: document edge casesMichael Haggerty
* 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 <>
2014-10-01close_lock_file(): if close fails, roll backMichael Haggerty
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 <>
2014-10-01commit_lock_file(): die() if called for unlocked lockfile objectMichael Haggerty
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 <>
2014-10-01api-lockfile: revise and expand the documentationMichael Haggerty
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 <>
2008-01-16close_lock_file(): new function in the lockfile APIBrandon Casey
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 <>
2008-01-16Document lockfile APIJunio C Hamano
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 <>
2007-12-15Start preparing the API documents.Junio C Hamano
Most of them are still stubs, but the procedure to build the HTML documentation, maintaining the index and installing the end product are there. I placed names of people who are likely to know the most about the topic in the stub files, so that volunteers will know whom to ask questions as needed. Signed-off-by: Junio C Hamano <>