gitout

A static git page generator
git clone https://git.bracken.jp/gitout.git
Log | Files | Refs | Submodules | README | LICENSE

cache.h (2883B)

      1 #ifndef GITOUT_WRITER_CACHE_CACHE_H_
      2 #define GITOUT_WRITER_CACHE_CACHE_H_
      3 
      4 #include <stdbool.h>
      5 #include <stdio.h>
      6 
      7 #include "git/commit.h"
      8 
      9 /* Commit log cache file.
     10  *
     11  * A cache consists of two files:
     12  *   - An existing cache, if it exists, which is read from cache_path at the
     13  *     start of a run.
     14  *   - An updated cache, written to a temp file, which overwrites the existing
     15  *     cache on invocation of cache_write.
     16  *
     17  * The fomat of a cache is:
     18  * LAST_CACHED_OID
     19  * FORMATTED_OID_ROW for LAST_CACHED_OID
     20  * FORMATTED_OID_ROW for LAST_CACHED_OID~1
     21  * ...
     22  * FORMATTED_OID_ROW for LAST_CACHED_OID~N
     23  *
     24  * Git OIDs are processed from most recent (HEAD) to least recent and added to
     25  * the cache via cache_add_commit_row. When LAST_CACHE_OID from the previous
     26  * cache (if it exists) is processed by cache_add_commit_row, the cache will
     27  * return false for all further invocations of cache_can_add_commits and no
     28  * further commits can be added.
     29  *
     30  * When complete, the cache can be written to the cache_path by invoking
     31  * cache_write. The cache should then be freed with cache_free.
     32  */
     33 typedef struct Cache Cache;
     34 
     35 /* Callback used to write a commit to out. */
     36 typedef void (*WriteCommitRow)(FILE* out, const GitCommit* commit);
     37 
     38 /* Allocates a cache.
     39  *
     40  * If an existing file exists at cache_path, it is opened for reading and the
     41  * OID header is read.
     42  *
     43  * A temporary file will be opened for writing which will be used to overwrite
     44  * the file at cache_path (if any), when cache_write is invoked.
     45  *
     46  * The WriteCommitRow parameter is a callback that is passed the output
     47  * stream of the cache and a GitCommit struct, and writes formatted output to
     48  * the stream. This callback function should emit the same content emitted as
     49  * is used to generating the commit log itself since the contents of this cache
     50  * will be inserted into the commit log for all commits after the cached OID.
     51  */
     52 Cache* cache_create(const char* cache_path, WriteCommitRow write_func);
     53 
     54 /* Frees the specified cache. */
     55 void cache_free(Cache* cache);
     56 
     57 /* Returns true if commits can be added to the cache.
     58  *
     59  * All commits newer than the OID read from the cache at creation time will be
     60  * added. Once cache_add_commit_row is invoked with the previously cached OID,
     61  * this function will return false.
     62  */
     63 bool cache_can_add_commits(const Cache* cache);
     64 
     65 /* Writes a commit row for the specified OID to cache.
     66  *
     67  * If this is the first commit to be written, the OID will be written to the
     68  * first line of the cache before the commit content is written.
     69  */
     70 void cache_add_commit_row(Cache* cache, const GitCommit* commit);
     71 
     72 /* Writes the cache to cache_path, overwriting any existing file.
     73  */
     74 void cache_write(Cache* cache);
     75 
     76 /* Copies the contents of the cache to the specified output stream. */
     77 void cache_copy_log(Cache* cache, FILE* out);
     78 
     79 #endif  // GITOUT_WRITER_CACHE_CACHE_H_