1 file changed, 21 insertions, 20 deletions

diff --git a/source/cache.h b/source/cache.hindex f8018be..db77999 100644--- a/source/cache.h+++ b/source/cache.h@@ -1,6 +1,7 @@ /*- * Since git has it's own cache.h which we include,- * lets test on CGIT_CACHE_H to avoid confusion+ * The front door to cgit's page cache. A caller hands over a key identifying+ * the request and a callback that renders the page, and gets back either the+ * copy already on disk or a freshly rendered one.  */  #ifndef CGIT_CACHE_H@@ -8,30 +9,30 @@  typedef void (*cache_fill_fn)(void); --/* Print cached content to stdout, generate the content if necessary.- *- * Parameters- *   size    max number of cache files- *   path    directory used to store cache files- *   key     the key used to lookup cache files- *   ttl     max cache time in seconds for this key- *   fn      content generator function for this key- *- * Return value- *   0 indicates success, everything else is an error+/*+ * Write the page for key to stdout, taking it from the cache when a fresh+ * slot for that key is there and rendering it through fn when it is not. size+ * is how many slots the cache may use and path is the directory holding them.+ * ttl is how many minutes a slot for this key stays fresh, where a negative+ * ttl never expires and a ttl of zero skips the cache for this request.+ * Returns 0 when the page was written, and an errno value when it was not.  */ extern int cache_process(int size, const char *path, const char *key, int ttl, 			 cache_fill_fn fn); --/* List info about all cache entries on stdout */+// Write one line per cache slot to stdout, giving its path, modification+// time, size and key. extern int cache_ls(const char *path); -/* Print a message to stdout */-__attribute__((format (printf,1,2)))-extern void cache_log(const char *format, ...);+/*+ * Give up on the slot being filled, discarding what has been rendered into it+ * and putting stdout back on the client. Anything that ends a request part way+ * through rendering has to call this before it writes what the visitor should+ * see, because until then stdout is the cache file and the visitor is on+ * course to receive nothing at all. Does nothing when no slot is being filled.+ */+extern void cache_abandon_fill(void);  extern unsigned long cache_hash_str(const char *str); -#endif /* CGIT_CACHE_H */+#endif // CGIT_CACHE_H
diff --git a/source/cache.h b/source/cache.h
index f8018be..db77999 100644
--- a/source/cache.h
+++ b/source/cache.h
@@ -1,6 +1,7 @@
 /*
- * Since git has it's own cache.h which we include,
- * lets test on CGIT_CACHE_H to avoid confusion
+ * The front door to cgit's page cache. A caller hands over a key identifying
+ * the request and a callback that renders the page, and gets back either the
+ * copy already on disk or a freshly rendered one.
  */
 
 #ifndef CGIT_CACHE_H
@@ -8,30 +9,30 @@
 
 typedef void (*cache_fill_fn)(void);
 
-
-/* Print cached content to stdout, generate the content if necessary.
- *
- * Parameters
- *   size    max number of cache files
- *   path    directory used to store cache files
- *   key     the key used to lookup cache files
- *   ttl     max cache time in seconds for this key
- *   fn      content generator function for this key
- *
- * Return value
- *   0 indicates success, everything else is an error
+/*
+ * Write the page for key to stdout, taking it from the cache when a fresh
+ * slot for that key is there and rendering it through fn when it is not. size
+ * is how many slots the cache may use and path is the directory holding them.
+ * ttl is how many minutes a slot for this key stays fresh, where a negative
+ * ttl never expires and a ttl of zero skips the cache for this request.
+ * Returns 0 when the page was written, and an errno value when it was not.
  */
 extern int cache_process(int size, const char *path, const char *key, int ttl,
 			 cache_fill_fn fn);
 
-
-/* List info about all cache entries on stdout */
+// Write one line per cache slot to stdout, giving its path, modification
+// time, size and key.
 extern int cache_ls(const char *path);
 
-/* Print a message to stdout */
-__attribute__((format (printf,1,2)))
-extern void cache_log(const char *format, ...);
+/*
+ * Give up on the slot being filled, discarding what has been rendered into it
+ * and putting stdout back on the client. Anything that ends a request part way
+ * through rendering has to call this before it writes what the visitor should
+ * see, because until then stdout is the cache file and the visitor is on
+ * course to receive nothing at all. Does nothing when no slot is being filled.
+ */
+extern void cache_abandon_fill(void);
 
 extern unsigned long cache_hash_str(const char *str);
 
-#endif /* CGIT_CACHE_H */
+#endif // CGIT_CACHE_H