]>
Commit | Line | Data |
---|---|---|
0b7cdc02 RB |
1 | /* |
2 | * Copyright (C) the libgit2 contributors. All rights reserved. | |
3 | * | |
4 | * This file is part of libgit2, distributed under the GNU GPL v2 with | |
5 | * a Linking Exception. For full terms see the included COPYING file. | |
6 | */ | |
7 | #ifndef INCLUDE_sorted_cache_h__ | |
8 | #define INCLUDE_sorted_cache_h__ | |
9 | ||
10 | #include "util.h" | |
11 | #include "fileops.h" | |
12 | #include "vector.h" | |
13 | #include "thread-utils.h" | |
14 | #include "pool.h" | |
15 | #include "strmap.h" | |
16 | ||
19b9a092 RB |
17 | #include <stddef.h> |
18 | ||
0b7cdc02 RB |
19 | /* |
20 | * The purpose of this data structure is to cache the parsed contents of a | |
805755f4 RB |
21 | * file (a.k.a. the backing file) where each item in the file can be |
22 | * identified by a key string and you want to both look them up by name | |
23 | * and traverse them in sorted order. Each item is assumed to itself end | |
24 | * in a GIT_FLEX_ARRAY. | |
0b7cdc02 RB |
25 | */ |
26 | ||
27 | typedef void (*git_sortedcache_free_item_fn)(void *payload, void *item); | |
28 | ||
29 | typedef struct { | |
30 | git_refcount rc; | |
8d9a85d4 | 31 | git_rwlock lock; |
0b7cdc02 RB |
32 | size_t item_path_offset; |
33 | git_sortedcache_free_item_fn free_item; | |
34 | void *free_item_payload; | |
35 | git_pool pool; | |
36 | git_vector items; | |
37 | git_strmap *map; | |
38 | git_futils_filestamp stamp; | |
39 | char path[GIT_FLEX_ARRAY]; | |
40 | } git_sortedcache; | |
41 | ||
8d9a85d4 | 42 | /* Create a new sortedcache |
0b7cdc02 | 43 | * |
8d9a85d4 | 44 | * Even though every sortedcache stores items with a GIT_FLEX_ARRAY at |
0b7cdc02 RB |
45 | * the end containing their key string, you have to provide the item_cmp |
46 | * sorting function because the sorting function doesn't get a payload | |
47 | * and therefore can't know the offset to the item key string. :-( | |
805755f4 RB |
48 | * |
49 | * @param out The allocated git_sortedcache | |
50 | * @param item_path_offset Offset to the GIT_FLEX_ARRAY item key in the | |
51 | * struct - use offsetof(struct mine, key-field) to get this | |
52 | * @param free_item Optional callback to free each item | |
53 | * @param free_item_payload Optional payload passed to free_item callback | |
54 | * @param item_cmp Compare the keys of two items | |
55 | * @param path The path to the backing store file for this cache; this | |
56 | * may be NULL. The cache makes it easy to load this and check | |
57 | * if it has been modified since the last load and/or write. | |
0b7cdc02 RB |
58 | */ |
59 | int git_sortedcache_new( | |
60 | git_sortedcache **out, | |
8d9a85d4 | 61 | size_t item_path_offset, /* use offsetof(struct, path-field) macro */ |
0b7cdc02 RB |
62 | git_sortedcache_free_item_fn free_item, |
63 | void *free_item_payload, | |
64 | git_vector_cmp item_cmp, | |
65 | const char *path); | |
66 | ||
8d9a85d4 | 67 | /* Copy a sorted cache |
0b7cdc02 | 68 | * |
8d9a85d4 | 69 | * - `copy_item` can be NULL to just use memcpy |
805755f4 | 70 | * - if `lock`, grabs read lock on `src` during copy and releases after |
0b7cdc02 RB |
71 | */ |
72 | int git_sortedcache_copy( | |
73 | git_sortedcache **out, | |
74 | git_sortedcache *src, | |
805755f4 | 75 | bool lock, |
0b7cdc02 RB |
76 | int (*copy_item)(void *payload, void *tgt_item, void *src_item), |
77 | void *payload); | |
78 | ||
8d9a85d4 RB |
79 | /* Free sorted cache (first calling `free_item` callbacks) |
80 | * | |
81 | * Don't call on a locked collection - it may acquire a write lock | |
3eecadcc | 82 | */ |
0b7cdc02 RB |
83 | void git_sortedcache_free(git_sortedcache *sc); |
84 | ||
8d9a85d4 | 85 | /* Increment reference count - balance with call to free */ |
0b7cdc02 RB |
86 | void git_sortedcache_incref(git_sortedcache *sc); |
87 | ||
8d9a85d4 RB |
88 | /* Get the pathname associated with this cache at creation time */ |
89 | const char *git_sortedcache_path(git_sortedcache *sc); | |
0b7cdc02 | 90 | |
8d9a85d4 RB |
91 | /* |
92 | * CACHE WRITE FUNCTIONS | |
93 | * | |
94 | * The following functions require you to have a writer lock to make the | |
95 | * modification. Some of the functions take a `wlock` parameter and | |
96 | * will optionally lock and unlock for you if that is passed as true. | |
97 | * | |
98 | */ | |
0b7cdc02 | 99 | |
8d9a85d4 RB |
100 | /* Lock sortedcache for write */ |
101 | int git_sortedcache_wlock(git_sortedcache *sc); | |
0b7cdc02 | 102 | |
8d9a85d4 RB |
103 | /* Unlock sorted cache when done with write */ |
104 | void git_sortedcache_wunlock(git_sortedcache *sc); | |
0b7cdc02 | 105 | |
805755f4 RB |
106 | /* Lock cache and load backing file into a buffer. |
107 | * | |
108 | * This grabs a write lock on the cache then looks at the modification | |
109 | * time and size of the file on disk. | |
110 | * | |
111 | * If the file appears to have changed, this loads the file contents into | |
112 | * the buffer and returns a positive value leaving the cache locked - the | |
113 | * caller should parse the file content, update the cache as needed, then | |
114 | * release the lock. NOTE: In this case, the caller MUST unlock the cache. | |
115 | * | |
116 | * If the file appears to be unchanged, then this automatically releases | |
117 | * the lock on the cache, clears the buffer, and returns 0. | |
8d9a85d4 | 118 | * |
0b7cdc02 RB |
119 | * @return 0 if up-to-date, 1 if out-of-date, <0 on error |
120 | */ | |
121 | int git_sortedcache_lockandload(git_sortedcache *sc, git_buf *buf); | |
122 | ||
8d9a85d4 RB |
123 | /* Refresh file timestamp after write completes |
124 | * You should already be holding the write lock when you call this. | |
125 | */ | |
126 | void git_sortedcache_updated(git_sortedcache *sc); | |
127 | ||
128 | /* Release all items in sorted cache | |
129 | * | |
130 | * If `wlock` is true, grabs write lock and releases when done, otherwise | |
131 | * you should already be holding a write lock when you call this. | |
132 | */ | |
133 | int git_sortedcache_clear(git_sortedcache *sc, bool wlock); | |
134 | ||
135 | /* Find and/or insert item, returning pointer to item data. | |
136 | * You should already be holding the write lock when you call this. | |
3eecadcc | 137 | */ |
0b7cdc02 RB |
138 | int git_sortedcache_upsert( |
139 | void **out, git_sortedcache *sc, const char *key); | |
140 | ||
8d9a85d4 RB |
141 | /* Removes entry at pos from cache |
142 | * You should already be holding the write lock when you call this. | |
143 | */ | |
144 | int git_sortedcache_remove(git_sortedcache *sc, size_t pos); | |
145 | ||
146 | /* | |
147 | * CACHE READ FUNCTIONS | |
148 | * | |
149 | * The following functions access items in the cache. To prevent the | |
150 | * results from being invalidated before they can be used, you should be | |
151 | * holding either a read lock or a write lock when using these functions. | |
152 | * | |
3eecadcc | 153 | */ |
8d9a85d4 RB |
154 | |
155 | /* Lock sortedcache for read */ | |
156 | int git_sortedcache_rlock(git_sortedcache *sc); | |
157 | ||
158 | /* Unlock sorted cache when done with read */ | |
159 | void git_sortedcache_runlock(git_sortedcache *sc); | |
160 | ||
161 | /* Lookup item by key - returns NULL if not found */ | |
0b7cdc02 RB |
162 | void *git_sortedcache_lookup(const git_sortedcache *sc, const char *key); |
163 | ||
8d9a85d4 RB |
164 | /* Get how many items are in the cache |
165 | * | |
166 | * You can call this function without holding a lock, but be aware | |
167 | * that it may change before you use it. | |
168 | */ | |
0b7cdc02 RB |
169 | size_t git_sortedcache_entrycount(const git_sortedcache *sc); |
170 | ||
8d9a85d4 RB |
171 | /* Lookup item by index - returns NULL if out of range */ |
172 | void *git_sortedcache_entry(git_sortedcache *sc, size_t pos); | |
0b7cdc02 | 173 | |
8d9a85d4 | 174 | /* Lookup index of item by key - returns GIT_ENOTFOUND if not found */ |
a4977169 RB |
175 | int git_sortedcache_lookup_index( |
176 | size_t *out, git_sortedcache *sc, const char *key); | |
177 | ||
0b7cdc02 | 178 | #endif |