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