LLVM 24.0.0git
PluginAPI_functions.h File Reference

Go to the source code of this file.

Macros

#define LLCAS_PUBLIC

Functions

LLVM_C_EXTERN_C_BEGIN LLCAS_PUBLIC void llcas_get_plugin_version (unsigned *major, unsigned *minor)
 Returns the LLCAS_VERSION_MAJOR and LLCAS_VERSION_MINOR values that the plugin was compiled with.
LLCAS_PUBLIC void llcas_string_dispose (char *)
 Releases memory of C string pointers provided by other functions.
LLCAS_PUBLIC void llcas_cancellable_cancel (llcas_cancellable_t)
 Cancels the asynchronous query associated with the llcas_cancellable_t.
LLCAS_PUBLIC void llcas_cancellable_dispose (llcas_cancellable_t)
 Releases memory associated with given llcas_cancellable_t.
LLCAS_PUBLIC llcas_cas_options_t llcas_cas_options_create (void)
 Options object to configure creation of llcas_cas_t.
LLCAS_PUBLIC void llcas_cas_options_dispose (llcas_cas_options_t)
LLCAS_PUBLIC void llcas_cas_options_set_client_version (llcas_cas_options_t, unsigned major, unsigned minor)
 Receives the LLCAS_VERSION_MAJOR and LLCAS_VERSION_MINOR values that the client was compiled with.
LLCAS_PUBLIC void llcas_cas_options_set_ondisk_path (llcas_cas_options_t, const char *path)
 Receives a local file-system path that the plugin should use for any on-disk resources/caches.
LLCAS_PUBLIC bool llcas_cas_options_set_option (llcas_cas_options_t, const char *name, const char *value, char **error)
 Receives a name/value strings pair, for the plugin to set as a custom option it supports.
LLCAS_PUBLIC llcas_cas_t llcas_cas_create (llcas_cas_options_t, char **error)
 Creates a new llcas_cas_t object.
LLCAS_PUBLIC void llcas_cas_dispose (llcas_cas_t)
 Releases memory of llcas_cas_t.
LLCAS_PUBLIC int64_t llcas_cas_get_ondisk_size (llcas_cas_t, char **error)
 Get the local storage size of the CAS/cache data in bytes.
LLCAS_PUBLIC bool llcas_cas_set_ondisk_size_limit (llcas_cas_t, int64_t size_limit, char **error)
 Set the size for limiting disk storage growth.
LLCAS_PUBLIC bool llcas_cas_prune_ondisk_data (llcas_cas_t, char **error)
 Prune local storage to reduce its size according to the desired size limit.
LLCAS_PUBLIC bool llcas_cas_validate (llcas_cas_t, bool check_hash, char **error)
 Validate the CAS contents.
LLCAS_PUBLIC charllcas_cas_get_hash_schema_name (llcas_cas_t)
LLCAS_PUBLIC unsigned llcas_digest_parse (llcas_cas_t, const char *printed_digest, uint8_t *bytes, size_t bytes_size, char **error)
 Parses the printed digest and returns the digest hash bytes.
LLCAS_PUBLIC bool llcas_digest_print (llcas_cas_t, llcas_digest_t, char **printed_id, char **error)
 Returns a string for the given digest bytes that can be passed to llcas_digest_parse.
LLCAS_PUBLIC bool llcas_cas_get_objectid (llcas_cas_t, llcas_digest_t digest, llcas_objectid_t *p_id, char **error)
 Provides the llcas_objectid_t value for the given llcas_digest_t.
LLCAS_PUBLIC llcas_digest_t llcas_objectid_get_digest (llcas_cas_t, llcas_objectid_t)
LLCAS_PUBLIC llcas_lookup_result_t llcas_cas_contains_object (llcas_cas_t, llcas_objectid_t, bool globally, char **error)
 Checks whether a llcas_objectid_t points to an existing object.
LLCAS_PUBLIC llcas_lookup_result_t llcas_cas_load_object (llcas_cas_t, llcas_objectid_t, llcas_loaded_object_t *, char **error)
 Loads the object that llcas_objectid_t points to.
LLCAS_PUBLIC void llcas_cas_load_object_async (llcas_cas_t, llcas_objectid_t, void *ctx_cb, llcas_cas_load_object_cb, llcas_cancellable_t *cancel_tok)
 Like llcas_cas_load_object but loading happens via a callback function.
LLCAS_PUBLIC bool llcas_cas_store_object (llcas_cas_t, llcas_data_t, const llcas_objectid_t *refs, size_t refs_count, llcas_objectid_t *p_id, char **error)
 Stores the object with the provided data buffer and llcas_objectid_t references, and provides its associated llcas_objectid_t.
LLCAS_PUBLIC bool llcas_cas_store_from_filepath (llcas_cas_t, const char *filepath, llcas_objectid_t *p_id, char **error)
 Stores the data of a file and provides its associated llcas_objectid_t.
LLCAS_PUBLIC llcas_data_t llcas_loaded_object_get_data (llcas_cas_t, llcas_loaded_object_t)
LLCAS_PUBLIC llcas_object_refs_t llcas_loaded_object_get_refs (llcas_cas_t, llcas_loaded_object_t)
LLCAS_PUBLIC size_t llcas_object_refs_get_count (llcas_cas_t, llcas_object_refs_t)
LLCAS_PUBLIC llcas_objectid_t llcas_object_refs_get_id (llcas_cas_t, llcas_object_refs_t, size_t index)
LLCAS_PUBLIC bool llcas_loaded_object_export_data_to_filepath (llcas_cas_t, llcas_loaded_object_t, const char *filepath, char **error)
 Exports the data of an object to a file path.
LLCAS_PUBLIC llcas_lookup_result_t llcas_actioncache_get_for_digest (llcas_cas_t, llcas_digest_t key, llcas_objectid_t *p_value, bool globally, char **error)
 Retrieves the llcas_objectid_t value associated with a key.
LLCAS_PUBLIC void llcas_actioncache_get_for_digest_async (llcas_cas_t, llcas_digest_t key, bool globally, void *ctx_cb, llcas_actioncache_get_cb, llcas_cancellable_t *cancel_tok)
 Like llcas_actioncache_get_for_digest but result is provided to a callback function.
LLCAS_PUBLIC bool llcas_actioncache_put_for_digest (llcas_cas_t, llcas_digest_t key, llcas_objectid_t value, bool globally, char **error)
 Associates a llcas_objectid_t value with a key.
LLCAS_PUBLIC void llcas_actioncache_put_for_digest_async (llcas_cas_t, llcas_digest_t key, llcas_objectid_t value, bool globally, void *ctx_cb, llcas_actioncache_put_cb, llcas_cancellable_t *cancel_tok)
 Like llcas_actioncache_put_for_digest but result is provided to a callback function.
LLCAS_PUBLIC bool llcas_actioncache_validate (llcas_cas_t, char **error)
 Validate the action cache contents.

Macro Definition Documentation

◆ LLCAS_PUBLIC

Function Documentation

◆ llcas_actioncache_get_for_digest()

LLCAS_PUBLIC llcas_lookup_result_t llcas_actioncache_get_for_digest ( llcas_cas_t ,
llcas_digest_t key,
llcas_objectid_t * p_value,
bool globally,
char ** error )

Retrieves the llcas_objectid_t value associated with a key.

Parameters
p_valuepointer to store the returned llcas_objectid_t object.
globallyif true it is a hint to the underlying implementation that the lookup is profitable to be done on a distributed caching level, not just locally. The implementation is free to ignore this flag.
erroroptional pointer to receive an error message if an error occurred. If set, the memory it points to needs to be released via llcas_string_dispose.
Returns
one of llcas_lookup_result_t.

References error, and LLCAS_PUBLIC.

◆ llcas_actioncache_get_for_digest_async()

LLCAS_PUBLIC void llcas_actioncache_get_for_digest_async ( llcas_cas_t ,
llcas_digest_t key,
bool globally,
void * ctx_cb,
llcas_actioncache_get_cb ,
llcas_cancellable_t * cancel_tok )

Like llcas_actioncache_get_for_digest but result is provided to a callback function.

Whether the call is asynchronous or not depends on the implementation.

Parameters
ctx_cbpointer to pass to the callback function.
[out]cancel_tokoptional pointer to receive a llcas_cancellable_t.

References LLCAS_PUBLIC.

◆ llcas_actioncache_put_for_digest()

LLCAS_PUBLIC bool llcas_actioncache_put_for_digest ( llcas_cas_t ,
llcas_digest_t key,
llcas_objectid_t value,
bool globally,
char ** error )

Associates a llcas_objectid_t value with a key.

It is invalid to set a different value to the same key.

Parameters
globallyif true it is a hint to the underlying implementation that the association is profitable to be done on a distributed caching level, not just locally. The implementation is free to ignore this flag.
erroroptional pointer to receive an error message if an error occurred. If set, the memory it points to needs to be released via llcas_string_dispose.
Returns
true if there was an error, false otherwise.

References error, and LLCAS_PUBLIC.

◆ llcas_actioncache_put_for_digest_async()

LLCAS_PUBLIC void llcas_actioncache_put_for_digest_async ( llcas_cas_t ,
llcas_digest_t key,
llcas_objectid_t value,
bool globally,
void * ctx_cb,
llcas_actioncache_put_cb ,
llcas_cancellable_t * cancel_tok )

Like llcas_actioncache_put_for_digest but result is provided to a callback function.

Whether the call is asynchronous or not depends on the implementation.

Parameters
ctx_cbpointer to pass to the callback function.
[out]cancel_tokoptional pointer to receive a llcas_cancellable_t.

References LLCAS_PUBLIC.

◆ llcas_actioncache_validate()

LLCAS_PUBLIC bool llcas_actioncache_validate ( llcas_cas_t ,
char ** error )

Validate the action cache contents.

Parameters
erroroptional pointer to receive an error message if an error occurred. If set, the memory it points to needs to be released via llcas_string_dispose.
Returns
true if there was an error, false otherwise.

References error, LLCAS_PUBLIC, and LLVM_C_EXTERN_C_END.

◆ llcas_cancellable_cancel()

LLCAS_PUBLIC void llcas_cancellable_cancel ( llcas_cancellable_t )

Cancels the asynchronous query associated with the llcas_cancellable_t.

References LLCAS_PUBLIC.

◆ llcas_cancellable_dispose()

LLCAS_PUBLIC void llcas_cancellable_dispose ( llcas_cancellable_t )

Releases memory associated with given llcas_cancellable_t.

References LLCAS_PUBLIC.

◆ llcas_cas_contains_object()

LLCAS_PUBLIC llcas_lookup_result_t llcas_cas_contains_object ( llcas_cas_t ,
llcas_objectid_t ,
bool globally,
char ** error )

Checks whether a llcas_objectid_t points to an existing object.

Parameters
globallyFor CAS implementations that distinguish between local CAS and remote/distributed CAS, globally set to false indicates that the lookup will be restricted to the local CAS, returning "not found" even if the object might exist in the remote CAS.
erroroptional pointer to receive an error message if an error occurred. If set, the memory it points to needs to be released via llcas_string_dispose.
Returns
one of llcas_lookup_result_t.

References error, and LLCAS_PUBLIC.

◆ llcas_cas_create()

LLCAS_PUBLIC llcas_cas_t llcas_cas_create ( llcas_cas_options_t ,
char ** error )

Creates a new llcas_cas_t object.

The objects returned from the other functions are only valid to use while the llcas_cas_t object that they came from is still valid.

Parameters
erroroptional pointer to receive an error message if an error occurred. If set, the memory it points to needs to be released via llcas_string_dispose.
Returns
NULL if there was an error.

References error, and LLCAS_PUBLIC.

◆ llcas_cas_dispose()

LLCAS_PUBLIC void llcas_cas_dispose ( llcas_cas_t )

Releases memory of llcas_cas_t.

After calling this it is invalid to keep using objects that originated from this llcas_cas_t instance.

References LLCAS_PUBLIC.

◆ llcas_cas_get_hash_schema_name()

LLCAS_PUBLIC char * llcas_cas_get_hash_schema_name ( llcas_cas_t )
Returns
the hash schema name that the plugin is using. The string memory it points to needs to be released via llcas_string_dispose.

References LLCAS_PUBLIC.

◆ llcas_cas_get_objectid()

LLCAS_PUBLIC bool llcas_cas_get_objectid ( llcas_cas_t ,
llcas_digest_t digest,
llcas_objectid_t * p_id,
char ** error )

Provides the llcas_objectid_t value for the given llcas_digest_t.

Parameters
digestthe digest bytes that the returned llcas_objectid_t represents.
p_idpointer to store the returned llcas_objectid_t object.
erroroptional pointer to receive an error message if an error occurred. If set, the memory it points to needs to be released via llcas_string_dispose.
Returns
true if there was an error, false otherwise.

References error, and LLCAS_PUBLIC.

◆ llcas_cas_get_ondisk_size()

LLCAS_PUBLIC int64_t llcas_cas_get_ondisk_size ( llcas_cas_t ,
char ** error )

Get the local storage size of the CAS/cache data in bytes.

Parameters
erroroptional pointer to receive an error message if an error occurred. If set, the memory it points to needs to be released via llcas_string_dispose.
Returns
the local storage size of the CAS/cache data, or -1 if the implementation does not support reporting such size, or -2 if an error occurred.

References error, and LLCAS_PUBLIC.

◆ llcas_cas_load_object()

Loads the object that llcas_objectid_t points to.

Parameters
erroroptional pointer to receive an error message if an error occurred. If set, the memory it points to needs to be released via llcas_string_dispose.
Returns
one of llcas_lookup_result_t.

References error, and LLCAS_PUBLIC.

◆ llcas_cas_load_object_async()

LLCAS_PUBLIC void llcas_cas_load_object_async ( llcas_cas_t ,
llcas_objectid_t ,
void * ctx_cb,
llcas_cas_load_object_cb ,
llcas_cancellable_t * cancel_tok )

Like llcas_cas_load_object but loading happens via a callback function.

Whether the call is asynchronous or not depends on the implementation.

Parameters
ctx_cbpointer to pass to the callback function.
[out]cancel_tokoptional pointer to receive a llcas_cancellable_t.

References LLCAS_PUBLIC.

◆ llcas_cas_options_create()

LLCAS_PUBLIC llcas_cas_options_t llcas_cas_options_create ( void )

Options object to configure creation of llcas_cas_t.

After passing to llcas_cas_create, its memory can be released via llcas_cas_options_dispose.

References LLCAS_PUBLIC.

◆ llcas_cas_options_dispose()

LLCAS_PUBLIC void llcas_cas_options_dispose ( llcas_cas_options_t )

References LLCAS_PUBLIC.

◆ llcas_cas_options_set_client_version()

LLCAS_PUBLIC void llcas_cas_options_set_client_version ( llcas_cas_options_t ,
unsigned major,
unsigned minor )

Receives the LLCAS_VERSION_MAJOR and LLCAS_VERSION_MINOR values that the client was compiled with.

Intended for assisting compatibility with different versions.

References LLCAS_PUBLIC.

◆ llcas_cas_options_set_ondisk_path()

LLCAS_PUBLIC void llcas_cas_options_set_ondisk_path ( llcas_cas_options_t ,
const char * path )

Receives a local file-system path that the plugin should use for any on-disk resources/caches.

References LLCAS_PUBLIC.

◆ llcas_cas_options_set_option()

LLCAS_PUBLIC bool llcas_cas_options_set_option ( llcas_cas_options_t ,
const char * name,
const char * value,
char ** error )

Receives a name/value strings pair, for the plugin to set as a custom option it supports.

These are usually passed through as invocation options and are opaque to the client.

Parameters
erroroptional pointer to receive an error message if an error occurred. If set, the memory it points to needs to be released via llcas_string_dispose.
Returns
true if there was an error, false otherwise.

References error, LLCAS_PUBLIC, and name.

◆ llcas_cas_prune_ondisk_data()

LLCAS_PUBLIC bool llcas_cas_prune_ondisk_data ( llcas_cas_t ,
char ** error )

Prune local storage to reduce its size according to the desired size limit.

Pruning can happen concurrently with other operations.

Returns
true if there was an error, false otherwise.

References error, and LLCAS_PUBLIC.

◆ llcas_cas_set_ondisk_size_limit()

LLCAS_PUBLIC bool llcas_cas_set_ondisk_size_limit ( llcas_cas_t ,
int64_t size_limit,
char ** error )

Set the size for limiting disk storage growth.

Parameters
size_limitthe maximum size limit in bytes. 0 means no limit. Negative values are invalid.
erroroptional pointer to receive an error message if an error occurred. If set, the memory it points to needs to be released via llcas_string_dispose.
Returns
true if there was an error, false otherwise.

References error.

◆ llcas_cas_store_from_filepath()

LLCAS_PUBLIC bool llcas_cas_store_from_filepath ( llcas_cas_t ,
const char * filepath,
llcas_objectid_t * p_id,
char ** error )

Stores the data of a file and provides its associated llcas_objectid_t.

An underlying implementation could perform optimizations that reduce I/O and disk space consumption.

If there are any concurrent modifications to the file, the contents in the CAS may be corrupt.

Parameters
filepathpath to the file.
p_idpointer to store the returned llcas_objectid_t object.
erroroptional pointer to receive an error message if an error occurred. If set, the memory it points to needs to be released via llcas_string_dispose.
Returns
true if there was an error, false otherwise.

References error, and LLCAS_PUBLIC.

◆ llcas_cas_store_object()

LLCAS_PUBLIC bool llcas_cas_store_object ( llcas_cas_t ,
llcas_data_t ,
const llcas_objectid_t * refs,
size_t refs_count,
llcas_objectid_t * p_id,
char ** error )

Stores the object with the provided data buffer and llcas_objectid_t references, and provides its associated llcas_objectid_t.

Parameters
refspointer to array of llcas_objectid_t. Can be NULL if refs_count is 0.
refs_countnumber of llcas_objectid_t objects in the array.
p_idpointer to store the returned llcas_objectid_t object.
erroroptional pointer to receive an error message if an error occurred. If set, the memory it points to needs to be released via llcas_string_dispose.
Returns
true if there was an error, false otherwise.

References error, and LLCAS_PUBLIC.

◆ llcas_cas_validate()

LLCAS_PUBLIC bool llcas_cas_validate ( llcas_cas_t ,
bool check_hash,
char ** error )

Validate the CAS contents.

Parameters
check_hashif true, the hash of each object is recomputed and compared against the one it is stored under.
erroroptional pointer to receive an error message if an error occurred. If set, the memory it points to needs to be released via llcas_string_dispose.
Returns
true if there was an error, false otherwise.

References error, and LLCAS_PUBLIC.

◆ llcas_digest_parse()

LLCAS_PUBLIC unsigned llcas_digest_parse ( llcas_cas_t ,
const char * printed_digest,
uint8_t * bytes,
size_t bytes_size,
char ** error )

Parses the printed digest and returns the digest hash bytes.

Parameters
printed_digesta C string that was previously provided by llcas_digest_print.
bytespointer to a buffer for writing the digest bytes. Can be NULL if bytes_size is 0.
bytes_sizethe size of the buffer.
erroroptional pointer to receive an error message if an error occurred. If set, the memory it points to needs to be released via llcas_string_dispose.
Returns
0 if there was an error. If bytes_size is smaller than the required size to fit the digest bytes, returns the required buffer size without writing to bytes. Otherwise writes the digest bytes to bytes and returns the number of written bytes.

References error, and LLCAS_PUBLIC.

◆ llcas_digest_print()

LLCAS_PUBLIC bool llcas_digest_print ( llcas_cas_t ,
llcas_digest_t ,
char ** printed_id,
char ** error )

Returns a string for the given digest bytes that can be passed to llcas_digest_parse.

Parameters
printed_idpointer to receive the printed digest string. The memory it points to needs to be released via llcas_string_dispose.
erroroptional pointer to receive an error message if an error occurred. If set, the memory it points to needs to be released via llcas_string_dispose.
Returns
true if there was an error, false otherwise.

References error, and LLCAS_PUBLIC.

◆ llcas_get_plugin_version()

LLVM_C_EXTERN_C_BEGIN LLCAS_PUBLIC void llcas_get_plugin_version ( unsigned * major,
unsigned * minor )

Returns the LLCAS_VERSION_MAJOR and LLCAS_VERSION_MINOR values that the plugin was compiled with.

Intended for assisting compatibility with different versions.

References LLCAS_PUBLIC.

◆ llcas_loaded_object_export_data_to_filepath()

LLCAS_PUBLIC bool llcas_loaded_object_export_data_to_filepath ( llcas_cas_t ,
llcas_loaded_object_t ,
const char * filepath,
char ** error )

Exports the data of an object to a file path.

It does not include any references of the object.

An underlying implementation could perform optimizations that reduce I/O and disk space consumption.

Parameters
filepaththe file path to write the data to.
erroroptional pointer to receive an error message if an error occurred. If set, the memory it points to needs to be released via llcas_string_dispose.
Returns
true if there was an error, false otherwise.

References error.

◆ llcas_loaded_object_get_data()

LLCAS_PUBLIC llcas_data_t llcas_loaded_object_get_data ( llcas_cas_t ,
llcas_loaded_object_t  )
Returns
the data buffer of the provided llcas_loaded_object_t. The buffer pointer must be 8-byte aligned and NULL terminated. The memory that the buffer points to is valid for the lifetime of the llcas_cas_t object.

References LLCAS_PUBLIC.

◆ llcas_loaded_object_get_refs()

LLCAS_PUBLIC llcas_object_refs_t llcas_loaded_object_get_refs ( llcas_cas_t ,
llcas_loaded_object_t  )
Returns
the references of the provided llcas_loaded_object_t.

◆ llcas_object_refs_get_count()

LLCAS_PUBLIC size_t llcas_object_refs_get_count ( llcas_cas_t ,
llcas_object_refs_t  )
Returns
the number of references in the provided llcas_object_refs_t.

References LLCAS_PUBLIC.

◆ llcas_object_refs_get_id()

LLCAS_PUBLIC llcas_objectid_t llcas_object_refs_get_id ( llcas_cas_t ,
llcas_object_refs_t ,
size_t index )
Returns
the llcas_objectid_t of the reference at index. It is invalid to pass an index that is out of the range of references.

References LLCAS_PUBLIC.

◆ llcas_objectid_get_digest()

LLCAS_PUBLIC llcas_digest_t llcas_objectid_get_digest ( llcas_cas_t ,
llcas_objectid_t  )
Returns
the llcas_digest_t value for the given llcas_objectid_t. The memory that the buffer points to is valid for the lifetime of the llcas_cas_t object.

References LLCAS_PUBLIC.

◆ llcas_string_dispose()

LLCAS_PUBLIC void llcas_string_dispose ( char * )

Releases memory of C string pointers provided by other functions.

References LLCAS_PUBLIC.