1 /*=========================================================================== 2 * 3 * PUBLIC DOMAIN NOTICE 4 * National Center for Biotechnology Information 5 * 6 * This software/database is a "United States Government Work" under the 7 * terms of the United States Copyright Act. It was written as part of 8 * the author's official duties as a United States Government employee and 9 * thus cannot be copyrighted. This software/database is freely available 10 * to the public for use. The National Library of Medicine and the U.S. 11 * Government have not placed any restriction on its use or reproduction. 12 * 13 * Although all reasonable efforts have been taken to ensure the accuracy 14 * and reliability of the software and data, the NLM and the U.S. 15 * Government do not and cannot warrant the performance or results that 16 * may be obtained by using this software or data. The NLM and the U.S. 17 * Government disclaim all warranties, express or implied, including 18 * warranties of performance, merchantability or fitness for any particular 19 * purpose. 20 * 21 * Please cite the author in any work or product based on this material. 22 * 23 * =========================================================================== 24 * 25 */ 26 27 #ifndef _h_kfs_pagefile_ 28 #define _h_kfs_pagefile_ 29 30 #ifndef _h_kfs_extern_ 31 #include <kfs/extern.h> 32 #endif 33 34 #ifndef _h_klib_defs_ 35 #include <klib/defs.h> 36 #endif 37 38 #ifdef __cplusplus 39 extern "C" { 40 #endif 41 42 43 /*-------------------------------------------------------------------------- 44 * forwards 45 */ 46 struct KFile; 47 48 49 /*-------------------------------------------------------------------------- 50 * KPage 51 * a reference counted page 52 */ 53 typedef struct KPage KPage; 54 55 56 /* AddRef 57 * Release 58 * ignores NULL references 59 */ 60 KFS_EXTERN rc_t CC KPageAddRef ( const KPage *self ); 61 KFS_EXTERN rc_t CC KPageRelease ( const KPage *self ); 62 63 64 /* Id 65 * returns page id 66 * 67 * "page_id" [ OUT ] - return parameter for page id 68 */ 69 KFS_EXTERN rc_t CC KPageId ( const KPage *self, uint32_t *page_id ); 70 71 72 /* ConstSize 73 * returns constant page size 74 */ 75 KFS_EXTERN size_t CC KPageConstSize ( void ); 76 77 78 /* AccessRead 79 * AccessUpdate 80 * gain access to page memory 81 * update access marks page as modified 82 * 83 * "mem" [ OUT ] - pointer to page 84 * 85 * "bytes" [ OUT, NULL OKAY ] - page size in bytes 86 */ 87 KFS_EXTERN rc_t CC KPageAccessRead ( const KPage *self, const void **mem, size_t *bytes ); 88 KFS_EXTERN rc_t CC KPageAccessUpdate ( KPage *self, void **mem, size_t *bytes ); 89 90 91 /*-------------------------------------------------------------------------- 92 * KPageFile 93 * presents some level of page management on top of a random-access KFile 94 */ 95 typedef struct KPageFile KPageFile; 96 97 98 /* Make 99 * creates a page file 100 * 101 * "pf" [ OUT ] - return parameter for page file 102 * 103 * "backing" [ IN ] - backing file 104 * NB - attaches a new reference to file 105 * does not take ownership 106 * 107 * "climit" [ IN ] - cache size limit 108 * 109 * "write_through" [ IN ] - if true, causes page flushing 110 * on each KPageRelease message if modified. 111 */ 112 KFS_EXTERN rc_t CC KPageFileMakeRead ( const KPageFile **pf, 113 struct KFile const *backing, size_t climit ); 114 KFS_EXTERN rc_t CC KPageFileMakeUpdate ( KPageFile **pf, 115 struct KFile *backing, size_t climit, bool write_through ); 116 117 118 /* AddRef 119 * Release 120 * ignores NULL references 121 */ 122 KFS_EXTERN rc_t CC KPageFileAddRef ( const KPageFile *self ); 123 KFS_EXTERN rc_t CC KPageFileRelease ( const KPageFile *self ); 124 125 126 /* Size 127 * returns size in bytes of file and cache 128 * 129 * "lsize" [ OUT, NULL OKAY ] - return parameter for logical size 130 * 131 * "fsize" [ OUT, NULL OKAY ] - return parameter for file size 132 * 133 * "csize" [ OUT, NULL OKAY ] - return parameter for cache size 134 */ 135 KFS_EXTERN rc_t CC KPageFileSize ( const KPageFile *self, 136 uint64_t *lsize, uint64_t *fsize, size_t *csize ); 137 138 139 /* SetSize 140 * extends or truncates underlying file 141 * may affect cache contents 142 * 143 * "size" [ IN ] - logical size 144 */ 145 KFS_EXTERN rc_t CC KPageFileSetSize ( KPageFile *self, uint64_t size ); 146 147 148 /* Alloc 149 * allocates a new page 150 * the page will be zeroed and initially unmodified 151 * 152 * "page" [ OUT ] - return parameter for page object 153 * 154 * "page_id" [ OUT, NULL OKAY ] - optional return parameter for page id 155 */ 156 KFS_EXTERN rc_t CC KPageFileAlloc ( KPageFile *self, KPage **page, uint32_t *page_id ); 157 158 159 /* Get 160 * returns an existing page 161 * 162 * "page" [ OUT ] - return parameter for page object 163 * 164 * "page_id" [ IN ] - id of page to retrieve 165 */ 166 KFS_EXTERN rc_t CC KPageFileGet ( KPageFile *self, KPage **page, uint32_t page_id ); 167 168 169 /* PosGet 170 * returns a page corresponding to position 171 * 172 * "page" [ OUT ] - return parameter for page object 173 * 174 * "offset" [ IN ] - offset to a byte within file 175 */ 176 KFS_EXTERN rc_t CC KPageFilePosGet ( KPageFile *self, KPage **page, uint64_t offset ); 177 178 179 /* DropBacking 180 * used immediately prior to releasing 181 * prevents modified pages from being flushed to disk 182 * renders object nearly useless 183 */ 184 KFS_EXTERN rc_t CC KPageFileDropBacking ( KPageFile *self ); 185 186 187 #ifdef __cplusplus 188 } 189 #endif 190 191 #endif /* _h_kfs_pagefile_ */ 192