Commit a2459dc5 authored by Matthieu Dorier's avatar Matthieu Dorier

added doxygen doc

parent f9d825d9
......@@ -8,28 +8,97 @@
extern "C" {
#endif
/**
* @brief REMI client type.
*/
typedef struct remi_client* remi_client_t;
#define REMI_CLIENT_NULL ((remi_client_t)0)
/**
* @brief REMI provider handle type.
*/
typedef struct remi_provider_handle* remi_provider_handle_t;
#define REMI_PROVIDER_HANDLE_NULL ((remi_provider_handle_t)0)
/**
* @brief Initializes a REMI client.
*
* @param[in] mid Margo instance.
* @param[out] client Resulting client.
*
* @return REMI_SUCCESS or error code defined in remi-common.h.
*/
int remi_client_init(margo_instance_id mid, remi_client_t* client);
/**
* @brief Finalizes a REMI client.
*
* @param client REMI client.
*
* @return REMI_SUCCESS or error code defined in remi-common.h.
*/
int remi_client_finalize(remi_client_t client);
/**
* @brief Creates a REMI provider handle.
*
* @param[in] client REMI client.
* @param[in] addr Mercury address of the provider.
* @param[in] provider_id Provider id.
* @param[out] handle Resulting provider handle.
*
* @return REMI_SUCCESS or error code defined in remi-common.h.
*/
int remi_provider_handle_create(
remi_client_t client,
hg_addr_t addr,
uint16_t provider_id,
remi_provider_handle_t* handle);
/**
* @brief Increments the reference counter of the provider handle.
*
* @param[in] handle Provider handle.
*
* @return REMI_SUCCESS or error code defined in remi-common.h.
*/
int remi_provider_handle_ref_incr(remi_provider_handle_t handle);
/**
* @brief Releases the provider handle. This function will decrement
* the reference count and free the provider handle if the reference
* count reaches 0.
*
* @param[in] handle Provider handle.
*
* @return REMI_SUCCESS or error code defined in remi-common.h.
*/
int remi_provider_handle_release(remi_provider_handle_t handle);
/**
* @brief Helper function wrapping margo_shutdown_remote_instance.
*
* @param[in] client REMI client.
* @param[in] addr Address of the remote instance to shutdown.
*
* @return REMI_SUCCESS or error code defined in remi-common.h.
*/
int remi_shutdown_service(remi_client_t client, hg_addr_t addr);
/**
* @brief Migrates a fileset to a remote provider. All the files
* of the local fileset will be transfered over RDMA to the destination
* provider and a remote fileset will be created with the provided
* remote root. If flag is set to REMI_REMOVE_SOURCE, the original
* files will be destroyed.
*
* @param handle Provider handle of the target provider.
* @param fileset Fileset to migrate.
* @param remote_root Root of the fileset when migrated.
* @param flag REMI_REMOVE_SOURCE or REMI_KEEP_SOURCE.
*
* @return REMI_SUCCESS or error code defined in remi-common.h.
*/
int remi_fileset_migrate(
remi_provider_handle_t handle,
remi_fileset_t fileset,
......
......@@ -7,8 +7,8 @@
extern "C" {
#endif
#define REMI_KEEP_SOURCE 0
#define REMI_REMOVE_SOURCE 1
#define REMI_KEEP_SOURCE 0 /* Keep the source files/directories */
#define REMI_REMOVE_SOURCE 1 /* Remove the source files/directories */
#define REMI_SUCCESS 0 /* Success */
#define REMI_ERR_ALLOCATION -1 /* Error allocating something */
......@@ -24,54 +24,176 @@ extern "C" {
#define REMI_ERR_FILE_EXISTS -11 /* File already exists */
#define REMI_ERR_IO -12 /* Error in I/O (stat, open, etc.) call */
/**
* @brief Fileset type.
*/
typedef struct remi_fileset* remi_fileset_t;
#define REMI_FILESET_NULL ((remi_fileset_t)0)
/**
* @brief Fileset callback type. This callback takes a file's name
* as first parameter and a pointer to user-provided arguments as the
* second parameter. It is used by the remi_fileset_foreach_file()
* function.
*/
typedef void (*remi_fileset_callback_t)(const char*, void*);
#define REMI_FILESET_CALLBACK_NULL ((remi_fileset_callback_t)0)
/**
* @brief Fileset metadata callback type. This callback takes a key
* (string), a value (string) and a pointer to user-provided arguments.
* It is used by the remi_fileset_foreach_metadata() function.
*/
typedef void (*remi_metadata_callback_t)(const char*, const char*, void*);
#define REMI_METADATA_CALLBACK_NULL ((remi_metadata_callback_t)0)
/**
* @brief Creates a new empty fileset. The fileset's root directory
* must be an absolute path.
*
* @param[in] fileset_class Class of the fileset.
* @param[in] fileset_root Root directory.
* @param[out] fileset Resulting fileset.
*
* @return REMI_SUCCESS or error code defined in remi-common.h.
*/
int remi_fileset_create(
const char* fileset_class,
const char* fileset_root,
remi_fileset_t* fileset);
/**
* @brief Frees a fileset. Passing a REMI_FILESET_NULL fileset
* to this function is valid.
*
* @param fileset Fileset to free.
*
* @return REMI_SUCCESS or error code defined in remi-common.h.
*/
int remi_fileset_free(remi_fileset_t fileset);
/**
* @brief Gets the class of the fileset. If buf is NULL, this
* function will set the size to the size required to hold the
* class name. If buf is not NULL, size should contain the
* maximum number of bytes available in the buffer. After the call,
* the buffer will contain the fileset's class name, and size will
* be set to the size of this class name (including null-terminator).
*
* @param[in] fileset Fileset from which to get the class name.
* @param[out] buf Buffer to hold the name.
* @param[inout] size Size of the buffer/name.
*
* @return REMI_SUCCESS or error code defined in remi-common.h.
*/
int remi_fileset_get_class(
remi_fileset_t fileset,
char* buf,
size_t* size);
/**
* @brief Gets the root of the fileset. If buf is NULL, this
* function will set the size to the size required to hold the
* root. If buf is not NULL, size should contain the
* maximum number of bytes available in the buffer. After the call,
* the buffer will contain the fileset's root, and size will
* be set to the size of this root (including null-terminator).
*
* @param[in] fileset Fileset from which to get the root.
* @param[out] buf Buffer to hold the root.
* @param[inout] size Size of the buffer/root.
*
* @return REMI_SUCCESS or error code defined in remi-common.h.
*/
int remi_fileset_get_root(
remi_fileset_t fileset,
char* buf,
size_t* size);
/**
* @brief Registers a file in the fileset. The provided path
* should be relative to the fileset's root. The file need not
* exist at the moment it is being registered (it needs to exist
* when migrating the fileset).
*
* @param fileset Fileset in which to register the file.
* @param filename File name.
*
* @return REMI_SUCCESS or error code defined in remi-common.h.
*/
int remi_fileset_register_file(
remi_fileset_t fileset,
const char* filename);
/**
* @brief Deregisters a file from the fileset. This deregisters
* the file only if the file has been added using remi_fileset_register_file.
* If an entire directory has been registered, individual files in the
* directory cannot be deregistered.
*
* @param fileset Fileset from which to deregister the file.
* @param filename File name.
*
* @return REMI_SUCCESS or error code defined in remi-common.h.
*/
int remi_fileset_deregister_file(
remi_fileset_t fileset,
const char* filename);
/**
* @brief Iterates over all the files in a fileset in alphabetical
* order and call the provided callback on the file's name and the
* provided user-arguments.
*
* @param fileset Fileset on which to iterate.
* @param callback Callback to call on each file.
* @param uargs User-provided arguments (may be NULL).
*
* @return REMI_SUCCESS or error code defined in remi-common.h.
*/
int remi_fileset_foreach_file(
remi_fileset_t fileset,
remi_fileset_callback_t callback,
void* uargs);
/**
* @brief Registers a metadata (key/value pair of strings) in the
* fileset. If a metadata already exists with the provided key,
* its value is overwritten.
*
* @param fileset Fileset in which to set the metadata.
* @param key Key.
* @param value Value.
*
* @return REMI_SUCCESS or error code defined in remi-common.h.
*/
int remi_fileset_register_metadata(
remi_fileset_t fileset,
const char* key,
const char* value);
/**
* @brief Deregisters a metadata from the fileset.
*
* @param fileset Fileset in which to deregister the metadata.
* @param key Key.
*
* @return REMI_SUCCESS or error code defined in remi-common.h.
*/
int remi_fileset_deregister_metadata(
remi_fileset_t fileset,
const char* key);
/**
* @brief Iterates over the key/value pairs and call the
* provided callback on each of them and on the user-provided argument.
*
* @param fileset Fileset on which to iterate over the metadata.
* @param callback Callback to call on the key/value pairs.
* @param uargs User-provided argument.
*
* @return REMI_SUCCESS or error code defined in remi-common.h.
*/
int remi_fileset_foreach_metadata(
remi_fileset_t fileset,
remi_metadata_callback_t callback,
......
......@@ -7,21 +7,52 @@
extern "C" {
#endif
#define REMI_ABT_POOL_DEFAULT ABT_POOL_NULL
#define REMI_PROVIDER_ID_DEFAULT 0
#define REMI_ABT_POOL_DEFAULT ABT_POOL_NULL /* Default Argobots pool for REMI */
#define REMI_PROVIDER_ID_DEFAULT 0 /* Default provider id for REMI */
/**
* @brief REMI provider type.
*/
typedef struct remi_provider* remi_provider_t;
#define REMI_PROVIDER_NULL ((remi_provider_t)0)
/**
* @brief Callback called when a migration completes. This callback
* takes the fileset that was newly created on the provider, as well
* as a pointer to user-provided arguments.
*/
typedef void (*remi_migration_callback_t)(remi_fileset_t, void*);
#define REMI_MIGRATION_CALLBACK_NULL ((remi_migration_callback_t)0)
/**
* @brief Registers a new REMI provider. The provider will be
* automatically destroyed upon finalizing the margo instance.
*
* @param[in] mid Margo instance.
* @param[in] provider_id Provider id.
* @param[in] pool Argobots pool.
* @param[out] provider Resulting provider.
*
* @return REMI_SUCCESS or error code defined in remi-common.h.
*/
int remi_provider_register(
margo_instance_id mid,
uint16_t provider_id,
ABT_pool pool,
remi_provider_t* provider);
/**
* @brief Registers a migration class by providing a callback
* to call when a fileset of that class is migrated.
*
* @param[in] provider Provider in which to register a migration class.
* @param[in] class_name Migration class name.
* @param[in] callback Callback to call after migration of a fileset of this class.
* @param[in] uargs User-argument to pass to the callback.
*
* @return REMI_SUCCESS or error code defined in remi-common.h.
*/
int remi_provider_register_migration_class(
remi_provider_t provider,
const char* class_name,
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment