kFsCache.h@ 2863

Last change on this file since 2863 was 2863, checked in by bird, 9 years ago
updates
Property svn:eol-style set to `native` Property svn:keywords set to `Id`
File size: 16.6 KB

Line
1	/* $Id: kFsCache.h 2863 2016-09-02 16:32:50Z bird $ */
2	/** @file
3	* kFsCache.c - NT directory content cache.
4	*/
5
6	/*
7	* Copyright (c) 2016 knut st. osmundsen <bird-kBuild-spamx@anduin.net>
8	*
9	* Permission is hereby granted, free of charge, to any person obtaining a
10	* copy of this software and associated documentation files (the "Software"),
11	* to deal in the Software without restriction, including without limitation
12	* the rights to use, copy, modify, merge, publish, distribute, sublicense,
13	* and/or sell copies of the Software, and to permit persons to whom the
14	* Software is furnished to do so, subject to the following conditions:
15	*
16	* The above copyright notice and this permission notice shall be included
17	* in all copies or substantial portions of the Software.
18	*
19	* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
20	* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
21	* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
22	* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
23	* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
24	* FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
25	* IN THE SOFTWARE.
26	*
27	* Alternatively, the content of this file may be used under the terms of the
28	* GPL version 2 or later, or LGPL version 2.1 or later.
29	*/
30
31	#ifndef ___lib_nt_kFsCache_h___
32	#define ___lib_nt_kFsCache_h___
33
34
35	#include <k/kHlp.h>
36	#include "ntstat.h"
37	#ifndef NDEBUG
38	# include <stdarg.h>
39	#endif
40
41
42	/** @def KFSCACHE_CFG_UTF16
43	* Whether to compile in the UTF-16 names support. */
44	#define KFSCACHE_CFG_UTF16 1
45	/** @def KFSCACHE_CFG_SHORT_NAMES
46	* Whether to compile in the short name support. */
47	#define KFSCACHE_CFG_SHORT_NAMES 1
48	/** @def KFSCACHE_CFG_PATH_HASH_TAB_SIZE
49	* Size of the path hash table. */
50	#define KFSCACHE_CFG_PATH_HASH_TAB_SIZE 16381
51	/** The max length paths we consider. */
52	#define KFSCACHE_CFG_MAX_PATH 1024
53	/** The max ANSI name length. */
54	#define KFSCACHE_CFG_MAX_ANSI_NAME (256*3 + 16)
55	/** The max UTF-16 name length. */
56	#define KFSCACHE_CFG_MAX_UTF16_NAME (256*2 + 16)
57
58
59
60	/** Special KFSOBJ::uCacheGen number indicating that it does not apply. */
61	#define KFSOBJ_CACHE_GEN_IGNORE KU32_MAX
62
63
64	/** @name KFSOBJ_TYPE_XXX - KFSOBJ::bObjType
65	* @{ */
66	/** Directory, type KFSDIR. */
67	#define KFSOBJ_TYPE_DIR KU8_C(0x01)
68	/** Regular file - type KFSOBJ. */
69	#define KFSOBJ_TYPE_FILE KU8_C(0x02)
70	/** Other file - type KFSOBJ. */
71	#define KFSOBJ_TYPE_OTHER KU8_C(0x03)
72	/** Caching of a negative result - type KFSOBJ.
73	* @remarks We will allocate enough space for the largest cache node, so this
74	* can metamorph into any other object should it actually turn up. */
75	#define KFSOBJ_TYPE_MISSING KU8_C(0x04)
76	///** Invalidated entry flag. */
77	//#define KFSOBJ_TYPE_F_INVALID KU8_C(0x20)
78	/** @} */
79
80	/** @name KFSOBJ_F_XXX - KFSOBJ::fFlags
81	* @{ */
82	/** Whether the file system update the modified timestamp of directories
83	* when something is removed from it or added to it.
84	* @remarks They say NTFS is the only windows filesystem doing this. */
85	#define KFSOBJ_F_WORKING_DIR_MTIME KU32_C(0x00000001)
86	/** NTFS file system volume. */
87	#define KFSOBJ_F_NTFS KU32_C(0x80000000)
88	/** @} */
89
90
91	#define IS_ALPHA(ch) ( ((ch) >= 'A' && (ch) <= 'Z') \|\| ((ch) >= 'a' && (ch) <= 'z') )
92	#define IS_SLASH(ch) ((ch) == '\\' \|\| (ch) == '/')
93
94
95
96
97	/** Pointer to a cache. */
98	typedef struct KFSCACHE *PKFSCACHE;
99	/** Pointer to a core object. */
100	typedef struct KFSOBJ *PKFSOBJ;
101	/** Pointer to a directory object. */
102	typedef struct KFSDIR *PKFSDIR;
103	/** Pointer to a directory hash table entry. */
104	typedef struct KFSOBJHASH *PKFSOBJHASH;
105
106
107	/**
108	* Directory hash table entry.
109	*
110	* There can be two of these per directory entry when the short name differs
111	* from the long name.
112	*/
113	typedef struct KFSOBJHASH
114	{
115	/** Pointer to the next entry with the same hash. */
116	PKFSOBJHASH pNext;
117	/** Pointer to the object. */
118	PKFSOBJ pObj;
119	} KFSOBJHASH;
120
121
122	/** Pointer to a user data item. */
123	typedef struct KFSUSERDATA *PKFSUSERDATA;
124	/**
125	* User data item associated with a cache node.
126	*/
127	typedef struct KFSUSERDATA
128	{
129	/** Pointer to the next piece of user data. */
130	PKFSUSERDATA pNext;
131	/** The key identifying this user. */
132	KUPTR uKey;
133	/** The destructor. */
134	void (*pfnDestructor)(PKFSCACHE pCache, PKFSOBJ pObj, PKFSUSERDATA pData);
135	} KFSUSERDATA;
136
137
138	/**
139	* Base cache node.
140	*/
141	typedef struct KFSOBJ
142	{
143	/** Magic value (KFSOBJ_MAGIC). */
144	KU32 u32Magic;
145	/** Number of references. */
146	KU32 volatile cRefs;
147	/** The cache generation, see KFSOBJ_CACHE_GEN_IGNORE. */
148	KU32 uCacheGen;
149	/** The object type, KFSOBJ_TYPE_XXX. */
150	KU8 bObjType;
151	/** Set if the Stats member is valid, clear if not. */
152	KBOOL fHaveStats;
153	/** Unused flags. */
154	KBOOL abUnused[2];
155	/** Flags, KFSOBJ_F_XXX. */
156	KU32 fFlags;
157
158	/** Pointer to the parent (directory).
159	* This is only NULL for a root. */
160	PKFSDIR pParent;
161
162	/** The directory name. (Allocated after the structure.) */
163	const char *pszName;
164	/** The length of pszName. */
165	KU16 cchName;
166	/** The length of the parent path (up to where pszName starts).
167	* @note This is valuable when constructing an absolute path to this node by
168	* means of the parent pointer (no need for recursion). */
169	KU16 cchParent;
170	#ifdef KFSCACHE_CFG_UTF16
171	/** The length of pwszName (in wchar_t's). */
172	KU16 cwcName;
173	/** The length of the parent UTF-16 path (in wchar_t's).
174	* @note This is valuable when constructing an absolute path to this node by
175	* means of the parent pointer (no need for recursion). */
176	KU16 cwcParent;
177	/** The UTF-16 object name. (Allocated after the structure.) */
178	const wchar_t *pwszName;
179	#endif
180
181	#ifdef KFSCACHE_CFG_SHORT_NAMES
182	/** The short object name. (Allocated after the structure, could be same
183	* as pszName.) */
184	const char *pszShortName;
185	/** The length of pszShortName. */
186	KU16 cchShortName;
187	/** The length of the short parent path (up to where pszShortName starts). */
188	KU16 cchShortParent;
189	# ifdef KFSCACHE_CFG_UTF16
190	/** The length of pwszShortName (in wchar_t's). */
191	KU16 cwcShortName;
192	/** The length of the short parent UTF-16 path (in wchar_t's). */
193	KU16 cwcShortParent;
194	/** The UTF-16 short object name. (Allocated after the structure, possibly
195	* same as pwszName.) */
196	const wchar_t *pwszShortName;
197	# endif
198	#endif
199
200	/** Pointer to the first user data item */
201	PKFSUSERDATA pUserDataHead;
202
203	/** Stats - only valid when fHaveStats is set. */
204	BirdStat_T Stats;
205	} KFSOBJ;
206
207	/** The magic for a KFSOBJ structure (Thelonious Sphere Monk). */
208	#define KFSOBJ_MAGIC KU32_C(0x19171010)
209
210
211	/**
212	* Directory node in the cache.
213	*/
214	typedef struct KFSDIR
215	{
216	/** The core object information. */
217	KFSOBJ Obj;
218
219	/** Child objects. */
220	PKFSOBJ *papChildren;
221	/** The number of child objects. */
222	KU32 cChildren;
223	/** The allocated size of papChildren. */
224	KU32 cChildrenAllocated;
225
226	/** Pointer to the hash table.
227	* @todo this isn't quite there yet, structure wise. sigh. */
228	PKFSOBJHASH paHashTab;
229	/** The size of the hash table.
230	* @remarks The hash table is optional and only used when there are a lot of
231	* entries in the directory. */
232	KU32 cHashTab;
233
234	/** Handle to the directory (we generally keep it open). */
235	#ifndef DECLARE_HANDLE
236	KUPTR hDir;
237	#else
238	HANDLE hDir;
239	#endif
240	/** The device number we queried/inherited when opening it. */
241	KU64 uDevNo;
242
243	/** The last write time sampled the last time the directory was refreshed.
244	* @remarks May differ from st_mtim because it will be updated when the
245	* parent directory is refreshed. */
246	KI64 iLastWrite;
247
248	/** Set if populated. */
249	KBOOL fPopulated;
250	/** Set if it needs re-populated. */
251	KBOOL fNeedRePopulating;
252	} KFSDIR;
253
254
255	/**
256	* Lookup errors.
257	*/
258	typedef enum KFSLOOKUPERROR
259	{
260	/** Lookup was a success. */
261	KFSLOOKUPERROR_SUCCESS = 0,
262	/** A path component was not found. */
263	KFSLOOKUPERROR_PATH_COMP_NOT_FOUND,
264	/** A path component is not a directory. */
265	KFSLOOKUPERROR_PATH_COMP_NOT_DIR,
266	/** The final path entry is not a directory (trailing slash). */
267	KFSLOOKUPERROR_NOT_DIR,
268	/** Not found. */
269	KFSLOOKUPERROR_NOT_FOUND,
270	/** The path is too long. */
271	KFSLOOKUPERROR_PATH_TOO_LONG,
272	/** Unsupported path type. */
273	KFSLOOKUPERROR_UNSUPPORTED,
274	/** We're out of memory. */
275	KFSLOOKUPERROR_OUT_OF_MEMORY,
276
277	/** Error opening directory. */
278	KFSLOOKUPERROR_DIR_OPEN_ERROR,
279	/** Error reading directory. */
280	KFSLOOKUPERROR_DIR_READ_ERROR,
281	/** UTF-16 to ANSI conversion error. */
282	KFSLOOKUPERROR_ANSI_CONVERSION_ERROR,
283	/** ANSI to UTF-16 conversion error. */
284	KFSLOOKUPERROR_UTF16_CONVERSION_ERROR,
285	/** Internal error. */
286	KFSLOOKUPERROR_INTERNAL_ERROR
287	} KFSLOOKUPERROR;
288
289
290	/** Pointer to an ANSI path hash table entry. */
291	typedef struct KFSHASHA *PKFSHASHA;
292	/**
293	* ANSI file system path hash table entry.
294	* The path hash table allows us to skip parsing and walking a path.
295	*/
296	typedef struct KFSHASHA
297	{
298	/** Next entry with the same hash table slot. */
299	PKFSHASHA pNext;
300	/** Path hash value. */
301	KU32 uHashPath;
302	/** The path length. */
303	KU16 cchPath;
304	/** Set if aboslute path. */
305	KBOOL fAbsolute;
306	/** The cache generation ID. */
307	KU32 uCacheGen;
308	/** The lookup error (when pFsObj is NULL). */
309	KFSLOOKUPERROR enmError;
310	/** The path. (Allocated after the structure.) */
311	const char *pszPath;
312	/** Pointer to the matching FS object.
313	* This is NULL for negative path entries? */
314	PKFSOBJ pFsObj;
315	} KFSHASHA;
316
317
318	#ifdef KFSCACHE_CFG_UTF16
319	/** Pointer to an UTF-16 path hash table entry. */
320	typedef struct KFSHASHW *PKFSHASHW;
321	/**
322	* UTF-16 file system path hash table entry. The path hash table allows us
323	* to skip parsing and walking a path.
324	*/
325	typedef struct KFSHASHW
326	{
327	/** Next entry with the same hash table slot. */
328	PKFSHASHW pNext;
329	/** Path hash value. */
330	KU32 uHashPath;
331	/** The path length (in wchar_t units). */
332	KU16 cwcPath;
333	/** Set if aboslute path. */
334	KBOOL fAbsolute;
335	/** The cache generation ID. */
336	KU32 uCacheGen;
337	/** The lookup error (when pFsObj is NULL). */
338	KFSLOOKUPERROR enmError;
339	/** The path. (Allocated after the structure.) */
340	const wchar_t *pwszPath;
341	/** Pointer to the matching FS object.
342	* This is NULL for negative path entries? */
343	PKFSOBJ pFsObj;
344	} KFSHASHW;
345	#endif
346
347
348	/** @name KFSCACHE_F_XXX
349	* @{ */
350	/** Whether to cache missing directory entries (KFSOBJ_TYPE_MISSING). */
351	#define KFSCACHE_F_MISSING_OBJECTS KU32_C(0x00000001)
352	/** Whether to cache missing paths. */
353	#define KFSCACHE_F_MISSING_PATHS KU32_C(0x00000002)
354	/** @} */
355
356
357	/**
358	* Directory cache instance.
359	*/
360	typedef struct KFSCACHE
361	{
362	/** Magic value (KFSCACHE_MAGIC). */
363	KU32 u32Magic;
364	/** Cache flags. */
365	KU32 fFlags;
366
367	/** The current cache generation for objects that already exists. */
368	KU32 uGeneration;
369	/** The current cache generation for missing objects, negative results, ++. */
370	KU32 uGenerationMissing;
371
372	/** Number of cache objects. */
373	KSIZE cObjects;
374	/** Memory occupied by the cache object structures. */
375	KSIZE cbObjects;
376	/** Number of lookups. */
377	KSIZE cLookups;
378	/** Number of hits in the path hash tables. */
379	KSIZE cPathHashHits;
380	/** Number of hits walking the file system hierarchy. */
381	KSIZE cWalkHits;
382
383	/** The root directory. */
384	KFSDIR RootDir;
385
386	/** File system hash table for ANSI filename strings. */
387	PKFSHASHA apAnsiPaths[KFSCACHE_CFG_PATH_HASH_TAB_SIZE];
388	/** Number of paths in the apAnsiPaths hash table. */
389	KSIZE cAnsiPaths;
390	/** Number of collisions in the apAnsiPaths hash table. */
391	KSIZE cAnsiPathCollisions;
392	/** Amount of memory used by the path entries. */
393	KSIZE cbAnsiPaths;
394
395	#ifdef KFSCACHE_CFG_UTF16
396	/** Number of paths in the apUtf16Paths hash table. */
397	KSIZE cUtf16Paths;
398	/** Number of collisions in the apUtf16Paths hash table. */
399	KSIZE cUtf16PathCollisions;
400	/** Amount of memory used by the UTF-16 path entries. */
401	KSIZE cbUtf16Paths;
402	/** File system hash table for UTF-16 filename strings. */
403	PKFSHASHW apUtf16Paths[KFSCACHE_CFG_PATH_HASH_TAB_SIZE];
404	#endif
405	} KFSCACHE;
406
407	/** Magic value for KFSCACHE::u32Magic (Jon Batiste). */
408	#define KFSCACHE_MAGIC KU32_C(0x19861111)
409
410
411	/** @def KW_LOG
412	* Generic logging.
413	* @param a Argument list for kFsCacheDbgPrintf */
414	#ifdef NDEBUG
415	# define KFSCACHE_LOG(a) do { } while (0)
416	#else
417	# define KFSCACHE_LOG(a) kFsCacheDbgPrintf a
418	void kFsCacheDbgPrintfV(const char *pszFormat, va_list va);
419	void kFsCacheDbgPrintf(const char *pszFormat, ...);
420	#endif
421
422
423	KBOOL kFsCacheDirEnsurePopuplated(PKFSCACHE pCache, PKFSDIR pDir, KFSLOOKUPERROR *penmError);
424	KBOOL kFsCacheDirAddChild(PKFSCACHE pCache, PKFSDIR pParent, PKFSOBJ pChild, KFSLOOKUPERROR *penmError);
425	PKFSOBJ kFsCacheCreateObject(PKFSCACHE pCache, PKFSDIR pParent,
426	char const pszName, KU16 cchName, wchar_t const pwszName, KU16 cwcName,
427	#ifdef KFSCACHE_CFG_SHORT_NAMES
428	char const pszShortName, KU16 cchShortName, wchar_t const pwszShortName, KU16 cwcShortName,
429	#endif
430	KU8 bObjType, KFSLOOKUPERROR *penmError);
431	PKFSOBJ kFsCacheCreateObjectW(PKFSCACHE pCache, PKFSDIR pParent, wchar_t const *pwszName, KU32 cwcName,
432	#ifdef KFSCACHE_CFG_SHORT_NAMES
433	wchar_t const *pwszShortName, KU32 cwcShortName,
434	#endif
435	KU8 bObjType, KFSLOOKUPERROR *penmError);
436	PKFSOBJ kFsCacheLookupA(PKFSCACHE pCache, const char pszPath, KFSLOOKUPERROR penmError);
437	PKFSOBJ kFsCacheLookupW(PKFSCACHE pCache, const wchar_t pwszPath, KFSLOOKUPERROR penmError);
438	PKFSOBJ kFsCacheLookupRelativeToDirA(PKFSCACHE pCache, PKFSDIR pParent, const char *pszPath, KU32 cchPath,
439	KFSLOOKUPERROR *penmError);
440	PKFSOBJ kFsCacheLookupRelativeToDirW(PKFSCACHE pCache, PKFSDIR pParent, const wchar_t *pwszPath, KU32 cwcPath,
441	KFSLOOKUPERROR *penmError);
442	PKFSOBJ kFsCacheLookupWithLengthA(PKFSCACHE pCache, const char pchPath, KSIZE cchPath, KFSLOOKUPERROR penmError);
443	PKFSOBJ kFsCacheLookupWithLengthW(PKFSCACHE pCache, const wchar_t pwcPath, KSIZE cwcPath, KFSLOOKUPERROR penmError);
444	PKFSOBJ kFsCacheLookupNoMissingA(PKFSCACHE pCache, const char pszPath, KFSLOOKUPERROR penmError);
445	PKFSOBJ kFsCacheLookupNoMissingW(PKFSCACHE pCache, const wchar_t pwszPath, KFSLOOKUPERROR penmError);
446
447
448	KU32 kFsCacheObjRelease(PKFSCACHE pCache, PKFSOBJ pObj);
449	KU32 kFsCacheObjRetain(PKFSOBJ pObj);
450	PKFSUSERDATA kFsCacheObjAddUserData(PKFSCACHE pCache, PKFSOBJ pObj, KUPTR uKey, KSIZE cbUserData);
451	PKFSUSERDATA kFsCacheObjGetUserData(PKFSCACHE pCache, PKFSOBJ pObj, KUPTR uKey);
452	KBOOL kFsCacheObjGetFullPathA(PKFSOBJ pObj, char *pszPath, KSIZE cbPath, char chSlash);
453	KBOOL kFsCacheObjGetFullPathW(PKFSOBJ pObj, wchar_t *pwszPath, KSIZE cwcPath, wchar_t wcSlash);
454	KBOOL kFsCacheObjGetFullShortPathA(PKFSOBJ pObj, char *pszPath, KSIZE cbPath, char chSlash);
455	KBOOL kFsCacheObjGetFullShortPathW(PKFSOBJ pObj, wchar_t *pwszPath, KSIZE cwcPath, wchar_t wcSlash);
456
457	KBOOL kFsCacheFileSimpleOpenReadClose(PKFSCACHE pCache, PKFSOBJ pFileObj, KU64 offStart, void *pvBuf, KSIZE cbToRead);
458
459	PKFSCACHE kFsCacheCreate(KU32 fFlags);
460	void kFsCacheDestroy(PKFSCACHE);
461	void kFsCacheInvalidateMissing(PKFSCACHE pFsCache);
462	void kFsCacheInvalidateAll(PKFSCACHE pFsCache);
463
464	#endif

Note: See TracBrowser for help on using the repository browser.

source: kBuild/trunk/src/lib/nt/kFsCache.h@ 2863

Download in other formats: