/* Include file cached obstack implementation.
- Written by Fred Fish (fnf@cygnus.com)
- Copyright 1995 Free Software Foundation, Inc.
+ Written by Fred Fish <fnf@cygnus.com>
+ Rewritten by Jim Blandy <jimb@cygnus.com>
+
+ Copyright 1999, 2000, 2002 Free Software Foundation, Inc.
This file is part of GDB.
#ifndef BCACHE_H
#define BCACHE_H 1
-#define BCACHE_HASHLENGTH 12 /* Number of bits in hash value */
-#define BCACHE_HASHSIZE (1 << BCACHE_HASHLENGTH)
-#define BCACHE_MAXLENGTH 128
-
-/* Note that the user data is stored in data[]. Since it can be any type,
- it needs to have the same alignment as the most strict alignment of
- any type on the host machine. So do it the same way obstack does. */
-
-struct hashlink
- {
- struct hashlink *next;
- union
- {
- char data[1];
- double dummy;
- }
- d;
- };
-
-/* BCACHE_DATA is used to get the address of the cached data. */
-
-#define BCACHE_DATA(p) ((p)->d.data)
-
-/* BCACHE_DATA_ALIGNMENT is used to get the offset of the start of
- cached data within the hashlink struct. This value, plus the
- size of the cached data, is the amount of space to allocate for
- a hashlink struct to hold the next pointer and the data. */
-
-#define BCACHE_DATA_ALIGNMENT \
- (((char *) BCACHE_DATA((struct hashlink*) 0) - (char *) 0))
-
-struct bcache
- {
- struct obstack cache;
- struct hashlink **indextable[BCACHE_MAXLENGTH];
- int cache_hits;
- int cache_misses;
- int cache_bytes;
- int cache_savings;
- int bcache_overflows;
- };
-
-extern void *
- bcache PARAMS ((void *bytes, int count, struct bcache * bcachep));
-
-extern void
-print_bcache_statistics PARAMS ((struct bcache *, char *));
+/* A bcache is a data structure for factoring out duplication in
+ read-only structures. You give the bcache some string of bytes S.
+ If the bcache already contains a copy of S, it hands you back a
+ pointer to its copy. Otherwise, it makes a fresh copy of S, and
+ hands you back a pointer to that. In either case, you can throw
+ away your copy of S, and use the bcache's.
+
+ The "strings" in question are arbitrary strings of bytes --- they
+ can contain zero bytes. You pass in the length explicitly when you
+ call the bcache function.
+
+ This means that you can put ordinary C objects in a bcache.
+ However, if you do this, remember that structs can contain `holes'
+ between members, added for alignment. These bytes usually contain
+ garbage. If you try to bcache two objects which are identical from
+ your code's point of view, but have different garbage values in the
+ structure's holes, then the bcache will treat them as separate
+ strings, and you won't get the nice elimination of duplicates you
+ were hoping for. So, remember to memset your structures full of
+ zeros before bcaching them!
+
+ You shouldn't modify the strings you get from a bcache, because:
+
+ - You don't necessarily know who you're sharing space with. If I
+ stick eight bytes of text in a bcache, and then stick an
+ eight-byte structure in the same bcache, there's no guarantee
+ those two objects don't actually comprise the same sequence of
+ bytes. If they happen to, the bcache will use a single byte
+ string for both of them. Then, modifying the structure will
+ change the string. In bizarre ways.
+
+ - Even if you know for some other reason that all that's okay,
+ there's another problem. A bcache stores all its strings in a
+ hash table. If you modify a string's contents, you will probably
+ change its hash value. This means that the modified string is
+ now in the wrong place in the hash table, and future bcache
+ probes will never find it. So by mutating a string, you give up
+ any chance of sharing its space with future duplicates. */
+
+
+struct bcache;
+
+/* Find a copy of the LENGTH bytes at ADDR in BCACHE. If BCACHE has
+ never seen those bytes before, add a copy of them to BCACHE. In
+ either case, return a pointer to BCACHE's copy of that string. */
+extern void *bcache (const void *addr, int length, struct bcache *bcache);
+
+/* Free all the storage used by BCACHE. */
+extern void bcache_xfree (struct bcache *bcache);
+
+/* Create a new bcache object. */
+extern struct bcache *bcache_xmalloc (void);
+
+/* Print statistics on BCACHE's memory usage and efficacity at
+ eliminating duplication. TYPE should be a string describing the
+ kind of data BCACHE holds. Statistics are printed using
+ `printf_filtered' and its ilk. */
+extern void print_bcache_statistics (struct bcache *bcache, char *type);
+extern int bcache_memory_used (struct bcache *bcache);
+
+/* The hash function */
+extern unsigned long hash(const void *addr, int length);
#endif /* BCACHE_H */
projects / deliverable / binutils-gdb.git / blobdiff