Commit 927458f6 authored by Kirill Smelkov's avatar Kirill Smelkov

bigfile/file.h: Cosmetics

- Provide brief top-level overview + refresh loadblk/storeblk/release comments.
- Add `typedef struct bigfile_ops bigfile_ops` that we usually add for all structs.
parent 34ed82c6
......@@ -2,7 +2,7 @@
#define _WENDELIN_BIGFILE_FILE_H_
/* Wendelin.bigfile | Base file class
* Copyright (C) 2014-2019 Nexedi SA and Contributors.
* Copyright (C) 2014-2020 Nexedi SA and Contributors.
* Kirill Smelkov <kirr@nexedi.com>
*
* This program is free software: you can Use, Study, Modify and Redistribute
......@@ -20,13 +20,16 @@
*
* See COPYING file for full licensing terms.
* See https://www.nexedi.com/licensing for rationale and options.
*/
/* Header wendelin/bigfile/file.h provides BigFile and interfaces that
* particular BigFile implementations must provide.
*
* ~~~~~~~~
*
* TODO description
* The interfaces are described in `struct bigfile_ops`.
* A particular BigFile implementation must provide loadblk/storeblk methods.
*
* Clients usually work with bigfiles via mapping files to memory -
* see wendelin/bigfile/virtmem.h and BigFileH for details. XXX
* Clients work with bigfiles via mapping files to memory - see
* wendelin/bigfile/virtmem.h and BigFileH for client-level API details.
*/
#include <stddef.h>
......@@ -51,24 +54,33 @@ struct BigFile {
};
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
// (in the future maybe in SIGSEGV context too?)
//
// TODO maybe also/instead use ram-fd based interface and then
// loadblk/storeblk would use splice(2) into/from that?
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);
};
typedef struct bigfile_ops bigfile_ops;
#ifdef __cplusplus
}
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment