1/*===----------------------------------------------------------------------===*\
2|* *|
3|* Part of the LLVM Project, under the Apache License v2.0 with LLVM *|
4|* Exceptions. *|
5|* See https://llvm.org/LICENSE.txt for license information. *|
6|* SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception *|
7|* *|
8|*===----------------------------------------------------------------------===*|
9|* *|
10|* The functions for the LLVM CAS plugin API. Intended for assisting *|
11|* implementations of the API. *|
12|* The API is experimental and subject to change. *|
13|* *|
14\*===----------------------------------------------------------------------===*/
15
16#ifndef LLVM_C_CAS_PLUGINAPI_FUNCTIONS_H
17#define LLVM_C_CAS_PLUGINAPI_FUNCTIONS_H
18
19#include "llvm-c/CAS/PluginAPI_types.h"
20#include "llvm-c/ExternC.h"
21
22#ifndef LLCAS_PUBLIC
23#ifdef _WIN32
24#define LLCAS_PUBLIC __declspec(dllexport)
25#else
26#define LLCAS_PUBLIC
27#endif
28#endif
29
30LLVM_C_EXTERN_C_BEGIN
31
32/**
33 * Returns the \c LLCAS_VERSION_MAJOR and \c LLCAS_VERSION_MINOR values that the
34 * plugin was compiled with.
35 * Intended for assisting compatibility with different versions.
36 */
37LLCAS_PUBLIC void llcas_get_plugin_version(unsigned *major, unsigned *minor);
38
39/**
40 * Releases memory of C string pointers provided by other functions.
41 */
42LLCAS_PUBLIC void llcas_string_dispose(char *);
43
44/**
45 * Cancels the asynchronous query associated with the \c llcas_cancellable_t.
46 */
47LLCAS_PUBLIC void llcas_cancellable_cancel(llcas_cancellable_t);
48
49/**
50 * Releases memory associated with given \c llcas_cancellable_t.
51 */
52LLCAS_PUBLIC void llcas_cancellable_dispose(llcas_cancellable_t);
53
54/**
55 * Options object to configure creation of \c llcas_cas_t. After passing to
56 * \c llcas_cas_create, its memory can be released via
57 * \c llcas_cas_options_dispose.
58 */
59LLCAS_PUBLIC llcas_cas_options_t llcas_cas_options_create(void);
60
61LLCAS_PUBLIC void llcas_cas_options_dispose(llcas_cas_options_t);
62
63/**
64 * Receives the \c LLCAS_VERSION_MAJOR and \c LLCAS_VERSION_MINOR values that
65 * the client was compiled with.
66 * Intended for assisting compatibility with different versions.
67 */
68LLCAS_PUBLIC void llcas_cas_options_set_client_version(llcas_cas_options_t,
69 unsigned major,
70 unsigned minor);
71
72/**
73 * Receives a local file-system path that the plugin should use for any on-disk
74 * resources/caches.
75 */
76LLCAS_PUBLIC void llcas_cas_options_set_ondisk_path(llcas_cas_options_t,
77 const char *path);
78
79/**
80 * Receives a name/value strings pair, for the plugin to set as a custom option
81 * it supports. These are usually passed through as invocation options and are
82 * opaque to the client.
83 *
84 * \param error optional pointer to receive an error message if an error
85 * occurred. If set, the memory it points to needs to be released via
86 * \c llcas_string_dispose.
87 * \returns true if there was an error, false otherwise.
88 */
89LLCAS_PUBLIC bool llcas_cas_options_set_option(llcas_cas_options_t,
90 const char *name,
91 const char *value, char **error);
92
93/**
94 * Creates a new \c llcas_cas_t object. The objects returned from the other
95 * functions are only valid to use while the \c llcas_cas_t object that they
96 * came from is still valid.
97 *
98 * \param error optional pointer to receive an error message if an error
99 * occurred. If set, the memory it points to needs to be released via
100 * \c llcas_string_dispose.
101 * \returns \c NULL if there was an error.
102 */
103LLCAS_PUBLIC llcas_cas_t llcas_cas_create(llcas_cas_options_t, char **error);
104
105/**
106 * Releases memory of \c llcas_cas_t. After calling this it is invalid to keep
107 * using objects that originated from this \c llcas_cas_t instance.
108 */
109LLCAS_PUBLIC void llcas_cas_dispose(llcas_cas_t);
110
111/**
112 * Get the local storage size of the CAS/cache data in bytes.
113 *
114 * \param error optional pointer to receive an error message if an error
115 * occurred. If set, the memory it points to needs to be released via
116 * \c llcas_string_dispose.
117 * \returns the local storage size of the CAS/cache data, or -1 if the
118 * implementation does not support reporting such size, or -2 if an error
119 * occurred.
120 */
121LLCAS_PUBLIC int64_t llcas_cas_get_ondisk_size(llcas_cas_t, char **error);
122
123/**
124 * Set the size for limiting disk storage growth.
125 *
126 * \param size_limit the maximum size limit in bytes. 0 means no limit. Negative
127 * values are invalid.
128 * \param error optional pointer to receive an error message if an error
129 * occurred. If set, the memory it points to needs to be released via
130 * \c llcas_string_dispose.
131 * \returns true if there was an error, false otherwise.
132 */
133LLCAS_PUBLIC bool
134llcas_cas_set_ondisk_size_limit(llcas_cas_t, int64_t size_limit, char **error);
135
136/**
137 * Prune local storage to reduce its size according to the desired size limit.
138 * Pruning can happen concurrently with other operations.
139 *
140 * \returns true if there was an error, false otherwise.
141 */
142LLCAS_PUBLIC bool llcas_cas_prune_ondisk_data(llcas_cas_t, char **error);
143
144/**
145 * Validate the CAS contents.
146 *
147 * \param check_hash if true, the hash of each object is recomputed and compared
148 * against the one it is stored under.
149 * \param error optional pointer to receive an error message if an error
150 * occurred. If set, the memory it points to needs to be released via
151 * \c llcas_string_dispose.
152 * \returns true if there was an error, false otherwise.
153 */
154LLCAS_PUBLIC bool llcas_cas_validate(llcas_cas_t, bool check_hash,
155 char **error);
156
157/**
158 * \returns the hash schema name that the plugin is using. The string memory it
159 * points to needs to be released via \c llcas_string_dispose.
160 */
161LLCAS_PUBLIC char *llcas_cas_get_hash_schema_name(llcas_cas_t);
162
163/**
164 * Parses the printed digest and returns the digest hash bytes.
165 *
166 * \param printed_digest a C string that was previously provided by
167 * \c llcas_digest_print.
168 * \param bytes pointer to a buffer for writing the digest bytes. Can be \c NULL
169 * if \p bytes_size is 0.
170 * \param bytes_size the size of the buffer.
171 * \param error optional pointer to receive an error message if an error
172 * occurred. If set, the memory it points to needs to be released via
173 * \c llcas_string_dispose.
174 * \returns 0 if there was an error. If \p bytes_size is smaller than the
175 * required size to fit the digest bytes, returns the required buffer size
176 * without writing to \c bytes. Otherwise writes the digest bytes to \p bytes
177 * and returns the number of written bytes.
178 */
179LLCAS_PUBLIC unsigned llcas_digest_parse(llcas_cas_t,
180 const char *printed_digest,
181 uint8_t *bytes, size_t bytes_size,
182 char **error);
183
184/**
185 * Returns a string for the given digest bytes that can be passed to
186 * \c llcas_digest_parse.
187 *
188 * \param printed_id pointer to receive the printed digest string. The memory it
189 * points to needs to be released via \c llcas_string_dispose.
190 * \param error optional pointer to receive an error message if an error
191 * occurred. If set, the memory it points to needs to be released via
192 * \c llcas_string_dispose.
193 * \returns true if there was an error, false otherwise.
194 */
195LLCAS_PUBLIC bool llcas_digest_print(llcas_cas_t, llcas_digest_t,
196 char **printed_id, char **error);
197
198/**
199 * Provides the \c llcas_objectid_t value for the given \c llcas_digest_t.
200 *
201 * \param digest the digest bytes that the returned \c llcas_objectid_t
202 * represents.
203 * \param p_id pointer to store the returned \c llcas_objectid_t object.
204 * \param error optional pointer to receive an error message if an error
205 * occurred. If set, the memory it points to needs to be released via
206 * \c llcas_string_dispose.
207 * \returns true if there was an error, false otherwise.
208 */
209LLCAS_PUBLIC bool llcas_cas_get_objectid(llcas_cas_t, llcas_digest_t digest,
210 llcas_objectid_t *p_id, char **error);
211
212/**
213 * \returns the \c llcas_digest_t value for the given \c llcas_objectid_t.
214 * The memory that the buffer points to is valid for the lifetime of the
215 * \c llcas_cas_t object.
216 */
217LLCAS_PUBLIC llcas_digest_t llcas_objectid_get_digest(llcas_cas_t,
218 llcas_objectid_t);
219
220/**
221 * Checks whether a \c llcas_objectid_t points to an existing object.
222 *
223 * \param globally For CAS implementations that distinguish between local CAS
224 * and remote/distributed CAS, \p globally set to false indicates that the
225 * lookup will be restricted to the local CAS, returning "not found" even if the
226 * object might exist in the remote CAS.
227 * \param error optional pointer to receive an error message if an error
228 * occurred. If set, the memory it points to needs to be released via
229 * \c llcas_string_dispose.
230 * \returns one of \c llcas_lookup_result_t.
231 */
232LLCAS_PUBLIC llcas_lookup_result_t llcas_cas_contains_object(llcas_cas_t,
233 llcas_objectid_t,
234 bool globally,
235 char **error);
236
237/**
238 * Loads the object that \c llcas_objectid_t points to.
239 *
240 * \param error optional pointer to receive an error message if an error
241 * occurred. If set, the memory it points to needs to be released via
242 * \c llcas_string_dispose.
243 * \returns one of \c llcas_lookup_result_t.
244 */
245LLCAS_PUBLIC llcas_lookup_result_t llcas_cas_load_object(
246 llcas_cas_t, llcas_objectid_t, llcas_loaded_object_t *, char **error);
247
248/**
249 * Like \c llcas_cas_load_object but loading happens via a callback function.
250 * Whether the call is asynchronous or not depends on the implementation.
251 *
252 * \param ctx_cb pointer to pass to the callback function.
253 *
254 * \param[out] cancel_tok optional pointer to receive a \c llcas_cancellable_t.
255 */
256LLCAS_PUBLIC void llcas_cas_load_object_async(llcas_cas_t, llcas_objectid_t,
257 void *ctx_cb,
258 llcas_cas_load_object_cb,
259 llcas_cancellable_t *cancel_tok);
260
261/**
262 * Stores the object with the provided data buffer and \c llcas_objectid_t
263 * references, and provides its associated \c llcas_objectid_t.
264 *
265 * \param refs pointer to array of \c llcas_objectid_t. Can be \c NULL if
266 * \p refs_count is 0.
267 * \param refs_count number of \c llcas_objectid_t objects in the array.
268 * \param p_id pointer to store the returned \c llcas_objectid_t object.
269 * \param error optional pointer to receive an error message if an error
270 * occurred. If set, the memory it points to needs to be released via
271 * \c llcas_string_dispose.
272 * \returns true if there was an error, false otherwise.
273 */
274LLCAS_PUBLIC bool llcas_cas_store_object(llcas_cas_t, llcas_data_t,
275 const llcas_objectid_t *refs,
276 size_t refs_count,
277 llcas_objectid_t *p_id, char **error);
278
279/**
280 * Stores the data of a file and provides its associated \c llcas_objectid_t.
281 *
282 * An underlying implementation could perform optimizations that reduce I/O
283 * and disk space consumption.
284 *
285 * If there are any concurrent modifications to the file, the contents in the
286 * CAS may be corrupt.
287 *
288 * \param filepath path to the file.
289 * \param p_id pointer to store the returned \c llcas_objectid_t object.
290 * \param error optional pointer to receive an error message if an error
291 * occurred. If set, the memory it points to needs to be released via
292 * \c llcas_string_dispose.
293 * \returns true if there was an error, false otherwise.
294 */
295LLCAS_PUBLIC bool llcas_cas_store_from_filepath(llcas_cas_t,
296 const char *filepath,
297 llcas_objectid_t *p_id,
298 char **error);
299
300/**
301 * \returns the data buffer of the provided \c llcas_loaded_object_t. The buffer
302 * pointer must be 8-byte aligned and \c NULL terminated. The memory that the
303 * buffer points to is valid for the lifetime of the \c llcas_cas_t object.
304 */
305LLCAS_PUBLIC llcas_data_t llcas_loaded_object_get_data(llcas_cas_t,
306 llcas_loaded_object_t);
307
308/**
309 * \returns a data buffer for the provided \c llcas_loaded_object_t that stays
310 * valid after the \c llcas_cas_t is disposed of. The buffer pointer must be
311 * 8-byte aligned and \c NULL terminated. It must be released via
312 * \c llcas_standalone_data_dispose, which may outlive the \c llcas_cas_t.
313 *
314 * This is an optimization over copying the buffer returned by
315 * \c llcas_loaded_object_get_data: an implementation that can hand out storage
316 * outliving itself, e.g. a mapping of a file it does not keep open, avoids the
317 * copy. Implementing it is optional, and requires
318 * \c llcas_standalone_data_dispose to be implemented as well.
319 */
320LLCAS_PUBLIC llcas_data_t
321 llcas_loaded_object_get_standalone_data(llcas_cas_t, llcas_loaded_object_t);
322
323/**
324 * Releases a buffer returned by \c llcas_loaded_object_get_standalone_data.
325 *
326 * This may be called after the \c llcas_cas_t that produced the buffer has
327 * been disposed of, so it must not depend on it.
328 */
329LLCAS_PUBLIC void llcas_standalone_data_dispose(llcas_data_t);
330
331/**
332 * \returns the references of the provided \c llcas_loaded_object_t.
333 */
334LLCAS_PUBLIC llcas_object_refs_t
335 llcas_loaded_object_get_refs(llcas_cas_t, llcas_loaded_object_t);
336
337/**
338 * \returns the number of references in the provided \c llcas_object_refs_t.
339 */
340LLCAS_PUBLIC size_t llcas_object_refs_get_count(llcas_cas_t,
341 llcas_object_refs_t);
342
343/**
344 * \returns the \c llcas_objectid_t of the reference at \p index. It is invalid
345 * to pass an index that is out of the range of references.
346 */
347LLCAS_PUBLIC llcas_objectid_t llcas_object_refs_get_id(llcas_cas_t,
348 llcas_object_refs_t,
349 size_t index);
350
351/**
352 * Exports the data of an object to a file path. It does not include any
353 * references of the object.
354 *
355 * An underlying implementation could perform optimizations that reduce I/O
356 * and disk space consumption.
357 *
358 * \param filepath the file path to write the data to.
359 * \param error optional pointer to receive an error message if an error
360 * occurred. If set, the memory it points to needs to be released via
361 * \c llcas_string_dispose.
362 * \returns true if there was an error, false otherwise.
363 */
364LLCAS_PUBLIC bool
365llcas_loaded_object_export_data_to_filepath(llcas_cas_t, llcas_loaded_object_t,
366 const char *filepath, char **error);
367
368/**
369 * Retrieves the \c llcas_objectid_t value associated with a \p key.
370 *
371 * \param p_value pointer to store the returned \c llcas_objectid_t object.
372 * \param globally if true it is a hint to the underlying implementation that
373 * the lookup is profitable to be done on a distributed caching level, not just
374 * locally. The implementation is free to ignore this flag.
375 * \param error optional pointer to receive an error message if an error
376 * occurred. If set, the memory it points to needs to be released via
377 * \c llcas_string_dispose.
378 * \returns one of \c llcas_lookup_result_t.
379 */
380LLCAS_PUBLIC llcas_lookup_result_t llcas_actioncache_get_for_digest(
381 llcas_cas_t, llcas_digest_t key, llcas_objectid_t *p_value, bool globally,
382 char **error);
383
384/**
385 * Like \c llcas_actioncache_get_for_digest but result is provided to a callback
386 * function. Whether the call is asynchronous or not depends on the
387 * implementation.
388 *
389 * \param ctx_cb pointer to pass to the callback function.
390 *
391 * \param[out] cancel_tok optional pointer to receive a \c llcas_cancellable_t.
392 */
393LLCAS_PUBLIC void llcas_actioncache_get_for_digest_async(
394 llcas_cas_t, llcas_digest_t key, bool globally, void *ctx_cb,
395 llcas_actioncache_get_cb, llcas_cancellable_t *cancel_tok);
396
397/**
398 * Associates a \c llcas_objectid_t \p value with a \p key. It is invalid to set
399 * a different \p value to the same \p key.
400 *
401 * \param globally if true it is a hint to the underlying implementation that
402 * the association is profitable to be done on a distributed caching level, not
403 * just locally. The implementation is free to ignore this flag.
404 * \param error optional pointer to receive an error message if an error
405 * occurred. If set, the memory it points to needs to be released via
406 * \c llcas_string_dispose.
407 * \returns true if there was an error, false otherwise.
408 */
409LLCAS_PUBLIC bool llcas_actioncache_put_for_digest(llcas_cas_t,
410 llcas_digest_t key,
411 llcas_objectid_t value,
412 bool globally, char **error);
413
414/**
415 * Like \c llcas_actioncache_put_for_digest but result is provided to a callback
416 * function. Whether the call is asynchronous or not depends on the
417 * implementation.
418 *
419 * \param ctx_cb pointer to pass to the callback function.
420 *
421 * \param[out] cancel_tok optional pointer to receive a \c llcas_cancellable_t.
422 */
423LLCAS_PUBLIC void llcas_actioncache_put_for_digest_async(
424 llcas_cas_t, llcas_digest_t key, llcas_objectid_t value, bool globally,
425 void *ctx_cb, llcas_actioncache_put_cb, llcas_cancellable_t *cancel_tok);
426
427/**
428 * Validate the action cache contents.
429 *
430 * \param error optional pointer to receive an error message if an error
431 * occurred. If set, the memory it points to needs to be released via
432 * \c llcas_string_dispose.
433 * \returns true if there was an error, false otherwise.
434 */
435LLCAS_PUBLIC bool llcas_actioncache_validate(llcas_cas_t, char **error);
436
437LLVM_C_EXTERN_C_END
438
439#endif /* LLVM_C_CAS_PLUGINAPI_FUNCTIONS_H */
440