Commit | Line | Data |
---|---|---|
c906108c | 1 | /* Include file cached obstack implementation. |
c2d11a7d JM |
2 | Written by Fred Fish <fnf@cygnus.com> |
3 | Rewritten by Jim Blandy <jimb@cygnus.com> | |
af5f3db6 AC |
4 | |
5 | Copyright 1999, 2000, 2002 Free Software Foundation, Inc. | |
c906108c | 6 | |
c5aa993b | 7 | This file is part of GDB. |
c906108c | 8 | |
c5aa993b JM |
9 | This program is free software; you can redistribute it and/or modify |
10 | it under the terms of the GNU General Public License as published by | |
11 | the Free Software Foundation; either version 2 of the License, or | |
12 | (at your option) any later version. | |
c906108c | 13 | |
c5aa993b JM |
14 | This program is distributed in the hope that it will be useful, |
15 | but WITHOUT ANY WARRANTY; without even the implied warranty of | |
16 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
17 | GNU General Public License for more details. | |
c906108c | 18 | |
c5aa993b JM |
19 | You should have received a copy of the GNU General Public License |
20 | along with this program; if not, write to the Free Software | |
21 | Foundation, Inc., 59 Temple Place - Suite 330, | |
22 | Boston, MA 02111-1307, USA. */ | |
c906108c SS |
23 | |
24 | #ifndef BCACHE_H | |
25 | #define BCACHE_H 1 | |
26 | ||
c2d11a7d JM |
27 | /* A bcache is a data structure for factoring out duplication in |
28 | read-only structures. You give the bcache some string of bytes S. | |
29 | If the bcache already contains a copy of S, it hands you back a | |
30 | pointer to its copy. Otherwise, it makes a fresh copy of S, and | |
31 | hands you back a pointer to that. In either case, you can throw | |
32 | away your copy of S, and use the bcache's. | |
33 | ||
34 | The "strings" in question are arbitrary strings of bytes --- they | |
35 | can contain zero bytes. You pass in the length explicitly when you | |
36 | call the bcache function. | |
37 | ||
38 | This means that you can put ordinary C objects in a bcache. | |
39 | However, if you do this, remember that structs can contain `holes' | |
40 | between members, added for alignment. These bytes usually contain | |
41 | garbage. If you try to bcache two objects which are identical from | |
42 | your code's point of view, but have different garbage values in the | |
43 | structure's holes, then the bcache will treat them as separate | |
44 | strings, and you won't get the nice elimination of duplicates you | |
45 | were hoping for. So, remember to memset your structures full of | |
46 | zeros before bcaching them! | |
47 | ||
48 | You shouldn't modify the strings you get from a bcache, because: | |
49 | ||
50 | - You don't necessarily know who you're sharing space with. If I | |
51 | stick eight bytes of text in a bcache, and then stick an | |
52 | eight-byte structure in the same bcache, there's no guarantee | |
53 | those two objects don't actually comprise the same sequence of | |
54 | bytes. If they happen to, the bcache will use a single byte | |
55 | string for both of them. Then, modifying the structure will | |
56 | change the string. In bizarre ways. | |
57 | ||
58 | - Even if you know for some other reason that all that's okay, | |
59 | there's another problem. A bcache stores all its strings in a | |
60 | hash table. If you modify a string's contents, you will probably | |
61 | change its hash value. This means that the modified string is | |
62 | now in the wrong place in the hash table, and future bcache | |
63 | probes will never find it. So by mutating a string, you give up | |
64 | any chance of sharing its space with future duplicates. */ | |
65 | ||
66 | ||
af5f3db6 | 67 | struct bcache; |
c2d11a7d JM |
68 | |
69 | /* Find a copy of the LENGTH bytes at ADDR in BCACHE. If BCACHE has | |
70 | never seen those bytes before, add a copy of them to BCACHE. In | |
71 | either case, return a pointer to BCACHE's copy of that string. */ | |
d85a5daf | 72 | extern void *bcache (const void *addr, int length, struct bcache *bcache); |
c2d11a7d | 73 | |
af5f3db6 AC |
74 | /* Free all the storage used by BCACHE. */ |
75 | extern void bcache_xfree (struct bcache *bcache); | |
76 | ||
77 | /* Create a new bcache object. */ | |
78 | extern struct bcache *bcache_xmalloc (void); | |
c2d11a7d JM |
79 | |
80 | /* Print statistics on BCACHE's memory usage and efficacity at | |
81 | eliminating duplication. TYPE should be a string describing the | |
82 | kind of data BCACHE holds. Statistics are printed using | |
83 | `printf_filtered' and its ilk. */ | |
84 | extern void print_bcache_statistics (struct bcache *bcache, char *type); | |
af5f3db6 AC |
85 | extern int bcache_memory_used (struct bcache *bcache); |
86 | ||
357e46e7 | 87 | /* The hash function */ |
d85a5daf | 88 | extern unsigned long hash(const void *addr, int length); |
af5f3db6 | 89 | |
c906108c | 90 | #endif /* BCACHE_H */ |