]>
Commit | Line | Data |
---|---|---|
958f9646 MH |
1 | #ifndef REFS_REF_CACHE_H |
2 | #define REFS_REF_CACHE_H | |
3 | ||
df308759 MH |
4 | struct ref_dir; |
5 | ||
6 | /* | |
7 | * If this ref_cache is filled lazily, this function is used to load | |
8 | * information into the specified ref_dir (shallow or deep, at the | |
9 | * option of the ref_store). dirname includes a trailing slash. | |
10 | */ | |
11 | typedef void fill_ref_dir_fn(struct ref_store *ref_store, | |
12 | struct ref_dir *dir, const char *dirname); | |
13 | ||
7c22bc8a MH |
14 | struct ref_cache { |
15 | struct ref_entry *root; | |
e00d1a4f | 16 | |
df308759 MH |
17 | /* A pointer to the ref_store whose cache this is: */ |
18 | struct ref_store *ref_store; | |
19 | ||
20 | /* | |
21 | * Function used (if necessary) to lazily-fill cache. May be | |
22 | * NULL. | |
23 | */ | |
24 | fill_ref_dir_fn *fill_ref_dir; | |
7c22bc8a MH |
25 | }; |
26 | ||
958f9646 MH |
27 | /* |
28 | * Information used (along with the information in ref_entry) to | |
29 | * describe a single cached reference. This data structure only | |
30 | * occurs embedded in a union in struct ref_entry, and only when | |
31 | * (ref_entry->flag & REF_DIR) is zero. | |
32 | */ | |
33 | struct ref_value { | |
34 | /* | |
35 | * The name of the object to which this reference resolves | |
36 | * (which may be a tag object). If REF_ISBROKEN, this is | |
37 | * null. If REF_ISSYMREF, then this is the name of the object | |
38 | * referred to by the last reference in the symlink chain. | |
39 | */ | |
40 | struct object_id oid; | |
958f9646 MH |
41 | }; |
42 | ||
43 | /* | |
44 | * Information used (along with the information in ref_entry) to | |
45 | * describe a level in the hierarchy of references. This data | |
46 | * structure only occurs embedded in a union in struct ref_entry, and | |
47 | * only when (ref_entry.flag & REF_DIR) is set. In that case, | |
48 | * (ref_entry.flag & REF_INCOMPLETE) determines whether the references | |
49 | * in the directory have already been read: | |
50 | * | |
51 | * (ref_entry.flag & REF_INCOMPLETE) unset -- a directory of loose | |
52 | * or packed references, already read. | |
53 | * | |
54 | * (ref_entry.flag & REF_INCOMPLETE) set -- a directory of loose | |
55 | * references that hasn't been read yet (nor has any of its | |
56 | * subdirectories). | |
57 | * | |
58 | * Entries within a directory are stored within a growable array of | |
59 | * pointers to ref_entries (entries, nr, alloc). Entries 0 <= i < | |
60 | * sorted are sorted by their component name in strcmp() order and the | |
61 | * remaining entries are unsorted. | |
62 | * | |
63 | * Loose references are read lazily, one directory at a time. When a | |
64 | * directory of loose references is read, then all of the references | |
65 | * in that directory are stored, and REF_INCOMPLETE stubs are created | |
66 | * for any subdirectories, but the subdirectories themselves are not | |
67 | * read. The reading is triggered by get_ref_dir(). | |
68 | */ | |
69 | struct ref_dir { | |
70 | int nr, alloc; | |
71 | ||
72 | /* | |
73 | * Entries with index 0 <= i < sorted are sorted by name. New | |
74 | * entries are appended to the list unsorted, and are sorted | |
75 | * only when required; thus we avoid the need to sort the list | |
76 | * after the addition of every reference. | |
77 | */ | |
78 | int sorted; | |
79 | ||
e00d1a4f MH |
80 | /* The ref_cache containing this entry: */ |
81 | struct ref_cache *cache; | |
958f9646 MH |
82 | |
83 | struct ref_entry **entries; | |
84 | }; | |
85 | ||
86 | /* | |
87 | * Bit values for ref_entry::flag. REF_ISSYMREF=0x01, | |
88 | * REF_ISPACKED=0x02, REF_ISBROKEN=0x04 and REF_BAD_NAME=0x08 are | |
89 | * public values; see refs.h. | |
90 | */ | |
91 | ||
958f9646 | 92 | /* ref_entry represents a directory of references */ |
a6e19bcd | 93 | #define REF_DIR 0x10 |
958f9646 MH |
94 | |
95 | /* | |
96 | * Entry has not yet been read from disk (used only for REF_DIR | |
97 | * entries representing loose references) | |
98 | */ | |
a6e19bcd | 99 | #define REF_INCOMPLETE 0x20 |
958f9646 MH |
100 | |
101 | /* | |
102 | * A ref_entry represents either a reference or a "subdirectory" of | |
103 | * references. | |
104 | * | |
105 | * Each directory in the reference namespace is represented by a | |
106 | * ref_entry with (flags & REF_DIR) set and containing a subdir member | |
107 | * that holds the entries in that directory that have been read so | |
108 | * far. If (flags & REF_INCOMPLETE) is set, then the directory and | |
109 | * its subdirectories haven't been read yet. REF_INCOMPLETE is only | |
110 | * used for loose reference directories. | |
111 | * | |
112 | * References are represented by a ref_entry with (flags & REF_DIR) | |
113 | * unset and a value member that describes the reference's value. The | |
114 | * flag member is at the ref_entry level, but it is also needed to | |
115 | * interpret the contents of the value field (in other words, a | |
116 | * ref_value object is not very much use without the enclosing | |
117 | * ref_entry). | |
118 | * | |
119 | * Reference names cannot end with slash and directories' names are | |
120 | * always stored with a trailing slash (except for the top-level | |
121 | * directory, which is always denoted by ""). This has two nice | |
122 | * consequences: (1) when the entries in each subdir are sorted | |
123 | * lexicographically by name (as they usually are), the references in | |
124 | * a whole tree can be generated in lexicographic order by traversing | |
125 | * the tree in left-to-right, depth-first order; (2) the names of | |
126 | * references and subdirectories cannot conflict, and therefore the | |
127 | * presence of an empty subdirectory does not block the creation of a | |
128 | * similarly-named reference. (The fact that reference names with the | |
129 | * same leading components can conflict *with each other* is a | |
130 | * separate issue that is regulated by refs_verify_refname_available().) | |
131 | * | |
132 | * Please note that the name field contains the fully-qualified | |
133 | * reference (or subdirectory) name. Space could be saved by only | |
134 | * storing the relative names. But that would require the full names | |
135 | * to be generated on the fly when iterating in do_for_each_ref(), and | |
136 | * would break callback functions, who have always been able to assume | |
137 | * that the name strings that they are passed will not be freed during | |
138 | * the iteration. | |
139 | */ | |
140 | struct ref_entry { | |
141 | unsigned char flag; /* ISSYMREF? ISPACKED? */ | |
142 | union { | |
143 | struct ref_value value; /* if not (flags&REF_DIR) */ | |
144 | struct ref_dir subdir; /* if (flags&REF_DIR) */ | |
145 | } u; | |
146 | /* | |
147 | * The full name of the reference (e.g., "refs/heads/master") | |
148 | * or the full name of the directory with a trailing slash | |
149 | * (e.g., "refs/heads/"): | |
150 | */ | |
151 | char name[FLEX_ARRAY]; | |
152 | }; | |
153 | ||
154 | /* | |
155 | * Return the index of the entry with the given refname from the | |
156 | * ref_dir (non-recursively), sorting dir if necessary. Return -1 if | |
157 | * no such entry is found. dir must already be complete. | |
158 | */ | |
159 | int search_ref_dir(struct ref_dir *dir, const char *refname, size_t len); | |
160 | ||
161 | struct ref_dir *get_ref_dir(struct ref_entry *entry); | |
162 | ||
163 | /* | |
164 | * Create a struct ref_entry object for the specified dirname. | |
165 | * dirname is the name of the directory with a trailing slash (e.g., | |
166 | * "refs/heads/") or "" for the top-level directory. | |
167 | */ | |
e00d1a4f | 168 | struct ref_entry *create_dir_entry(struct ref_cache *cache, |
958f9646 MH |
169 | const char *dirname, size_t len, |
170 | int incomplete); | |
171 | ||
172 | struct ref_entry *create_ref_entry(const char *refname, | |
c1da06c6 | 173 | const struct object_id *oid, int flag); |
958f9646 | 174 | |
7c22bc8a MH |
175 | /* |
176 | * Return a pointer to a new `ref_cache`. Its top-level starts out | |
df308759 MH |
177 | * marked incomplete. If `fill_ref_dir` is non-NULL, it is the |
178 | * function called to fill in incomplete directories in the | |
179 | * `ref_cache` when they are accessed. If it is NULL, then the whole | |
180 | * `ref_cache` must be filled (including clearing its directories' | |
099a912a MH |
181 | * `REF_INCOMPLETE` bits) before it is used, and `refs` can be NULL, |
182 | * too. | |
7c22bc8a | 183 | */ |
df308759 MH |
184 | struct ref_cache *create_ref_cache(struct ref_store *refs, |
185 | fill_ref_dir_fn *fill_ref_dir); | |
7c22bc8a MH |
186 | |
187 | /* | |
188 | * Free the `ref_cache` and all of its associated data. | |
189 | */ | |
190 | void free_ref_cache(struct ref_cache *cache); | |
958f9646 MH |
191 | |
192 | /* | |
193 | * Add a ref_entry to the end of dir (unsorted). Entry is always | |
194 | * stored directly in dir; no recursion into subdirectories is | |
195 | * done. | |
196 | */ | |
197 | void add_entry_to_dir(struct ref_dir *dir, struct ref_entry *entry); | |
198 | ||
199 | /* | |
200 | * Remove the entry with the given name from dir, recursing into | |
201 | * subdirectories as necessary. If refname is the name of a directory | |
202 | * (i.e., ends with '/'), then remove the directory and its contents. | |
203 | * If the removal was successful, return the number of entries | |
204 | * remaining in the directory entry that contained the deleted entry. | |
205 | * If the name was not found, return -1. Please note that this | |
206 | * function only deletes the entry from the cache; it does not delete | |
207 | * it from the filesystem or ensure that other cache entries (which | |
208 | * might be symbolic references to the removed entry) are updated. | |
209 | * Nor does it remove any containing dir entries that might be made | |
210 | * empty by the removal. dir must represent the top-level directory | |
211 | * and must already be complete. | |
212 | */ | |
213 | int remove_entry_from_dir(struct ref_dir *dir, const char *refname); | |
214 | ||
215 | /* | |
216 | * Add a ref_entry to the ref_dir (unsorted), recursing into | |
217 | * subdirectories as necessary. dir must represent the top-level | |
218 | * directory. Return 0 on success. | |
219 | */ | |
220 | int add_ref_entry(struct ref_dir *dir, struct ref_entry *ref); | |
221 | ||
958f9646 MH |
222 | /* |
223 | * Find the value entry with the given name in dir, sorting ref_dirs | |
224 | * and recursing into subdirectories as necessary. If the name is not | |
225 | * found or it corresponds to a directory entry, return NULL. | |
226 | */ | |
227 | struct ref_entry *find_ref_entry(struct ref_dir *dir, const char *refname); | |
228 | ||
059ae35a MH |
229 | /* |
230 | * Start iterating over references in `cache`. If `prefix` is | |
231 | * specified, only include references whose names start with that | |
232 | * prefix. If `prime_dir` is true, then fill any incomplete | |
8738a8a4 MH |
233 | * directories before beginning the iteration. The output is ordered |
234 | * by refname. | |
059ae35a MH |
235 | */ |
236 | struct ref_iterator *cache_ref_iterator_begin(struct ref_cache *cache, | |
237 | const char *prefix, | |
238 | int prime_dir); | |
958f9646 | 239 | |
958f9646 | 240 | #endif /* REFS_REF_CACHE_H */ |