.

include/wendelin/bigfile/file.h

@@ -49,17 +49,28 @@ typedef struct BigFile BigFile;
 
 /* bigfile_ops defines interface that BigFile implementations must provide. */
 struct bigfile_ops {
-    /* load/store file block to/from memory.
-     * NOTE len(buf) must be = file->blksize
+    /* loadblk is called to load file block into memory.
      *
+     * NOTE loadblk is called from SIGSEGV signal handler context.
+     *
+     * len(buf) must be = file->blksize.
      * @return  0 - ok      !0 - fail
      */
-    // XXX loadblk  - called from SIGSEGV context;
-    //     storeblk - called from usual context
     int  (*loadblk)  (BigFile *file, blk_t blk, void *buf);
+
+    /* storeblk is called to store file block from memory.
+     *
+     * NOTE contrary to loadblk, storeblk is called from regular context.
+     *
+     * len(buf) must be = file->blksize.
+     * @return  0 - ok      !0 - fail
+     */
     int  (*storeblk) (BigFile *file, blk_t blk, const void *buf);
 
-    /* release file */
+    /* release is called to release resources associated with file.
+     *
+     * The file is not otherwise used at the time of and past release call.
+     */
     void (*release)  (BigFile *file);
 };