refs/ref-cache.h

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