cache.h (3666B)
1 #ifndef GOUT_WRITER_CACHE_CACHE_H_ 2 #define GOUT_WRITER_CACHE_CACHE_H_ 3 4 #include <stdbool.h> 5 #include <stdio.h> 6 7 #include "git/commit.h" 8 #include "utils.h" 9 10 /* Commit log cache file. 11 * 12 * A cache consists of two files: 13 * - An existing cache, if it exists, which is read from cache_path at the 14 * start of a run. 15 * - An updated cache, written to a temp file, which overwrites the existing 16 * cache on invocation of cache_write. 17 * 18 * The fomat of a cache is: 19 * LAST_CACHED_OID 20 * FORMATTED_OID_ROW for LAST_CACHED_OID 21 * FORMATTED_OID_ROW for LAST_CACHED_OID~1 22 * ... 23 * FORMATTED_OID_ROW for LAST_CACHED_OID~N 24 * 25 * Git OIDs are processed from most recent (HEAD) to least recent and added to 26 * the cache via cache_add_commit_row. When LAST_CACHE_OID from the previous 27 * cache (if it exists) is processed by cache_add_commit_row, the cache will 28 * return false for all further invocations of cache_can_add_commits and no 29 * further commits can be added. 30 * 31 * When complete, the cache can be written to the cache_path by invoking 32 * cache_write. The cache should then be freed with cache_free. 33 */ 34 typedef struct Cache Cache; 35 36 /* Callback used to write a commit to out. */ 37 typedef void (*WriteCommitRow)(FILE* out, const GitCommit* commit); 38 39 /* Allocates a cache. 40 * 41 * The cache_in stream is used to read the previously cached OID and log data. 42 * It may be NULL if no previous cache exists. 43 * 44 * The cache_out stream is used to write the updated cache. 45 * 46 * Ownership of the streams is NOT taken by the Cache object. 47 * 48 * The WriteCommitRow parameter is a callback that is passed the output 49 * stream of the cache and a GitCommit struct, and writes formatted output to 50 * the stream. This callback function should emit the same content emitted as 51 * is used to generating the commit log itself since the contents of this cache 52 * will be inserted into the commit log for all commits after the cached OID. 53 */ 54 Cache* cache_create(FILE* cache_in, FILE* cache_out, WriteCommitRow write_func); 55 56 /* Higher-level API that manages its own files. 57 * 58 * Opens the cache at the specified path for reading, and creates a temporary 59 * file for writing the updated cache. 60 * 61 * Returns a Cache object that owns the opened file streams and paths. 62 */ 63 Cache* cache_open(const FileSystem* fs, 64 const char* path, 65 WriteCommitRow write_func); 66 67 /* Frees the specified cache. If the cache was created via cache_open, the 68 * associated file streams and paths are also freed. 69 */ 70 void cache_free(Cache* cache); 71 72 /* Returns true if commits can be added to the cache. 73 * 74 * All commits newer than the OID read from the cache at creation time will be 75 * added. Once cache_add_commit_row is invoked with the previously cached OID, 76 * this function will return false. 77 */ 78 bool cache_can_add_commits(const Cache* cache); 79 80 /* Writes a commit row for the specified OID to cache. 81 * 82 * If this is the first commit to be written, the OID will be written to the 83 * first line of the cache before the commit content is written. 84 */ 85 void cache_add_commit_row(Cache* cache, const GitCommit* commit); 86 87 /* Finishes the cache processing by appending any remaining data from the 88 * input stream to the output stream. 89 */ 90 void cache_finish(Cache* cache); 91 92 /* Finishes, closes files, renames the temporary cache file to the final path, 93 * and copies the log contents to the specified output stream. 94 */ 95 void cache_close_and_replace(Cache* cache, FILE* out); 96 97 /* Copies the contents of the cache stream to the specified output stream, 98 * skipping the OID header. 99 */ 100 void cache_copy_log(FILE* cache_in, FILE* out); 101 102 #endif // GOUT_WRITER_CACHE_CACHE_H_