C API Documentation

flock-backend.h

Typedefs

typedef struct flock_backend_init_args flock_backend_init_args_t

Initialization arguments.

Note

The backend’s init_group can call json_object_get on the config to increase its reference count and keep it internally (the provider does not modify it).

Note

The backend’s init_group can move the initial_view internally. If it does it, it should memset the flock_backend_init_args’s initial_view field to 0 so that the provider does not free it.

Note

The provided member_update_callback and metadata_update_callback need to be called by the backend whenever a member leaves or joins, and whenever the metadata is updated, respectively. When called, these function must be passed the provided callback_context.

Note

The backend should NOT use margo_addr_self to get its own address as it may be behind a gateway. Instead, the self_addr_str field should be used. This will have been initialized to a public address by the gateway system.

typedef flock_return_t (*flock_backend_init_fn)(flock_backend_init_args_t *args, void**)

Allocates and initializes the state of the backend.

Note

This function may move some of the fields of the flock_backend_init_args_t (see comments about flock_backend_init_args_t above).

Param flock_backend_init_args_t*

[in] Initialization arguments.

Param void**

[out] Pointer to the allocated state.

typedef flock_return_t (*flock_backend_finalize_fn)(void*)

Finalizes and deallocate the state of the backend.

Param void*

Pointer to the backend’s state.

typedef flock_return_t (*flock_backend_get_config_fn)(void*, void (*)(void*, const struct json_object*), void*)

Get the config of the backend and pass it to the provided function pointer.

Param void*

Pointer to the backend’s state.

Param void

(*)(void*, const struct json_object*) Function to call on the config.

Param void*

Context to pass to the function.

typedef flock_return_t (*flock_backend_get_view_fn)(void*, void (*)(void*, const flock_group_view_t*), void*)

Get the group view held by the backend.

@important This function should NOT lock the view using the view’s mtx field.

Param void*

Pointer to the backend’s state.

Param void

(*)(void*, const flock_group_view_t*) Function to call on the group view.

Param void*

Context to pass to the function.

typedef flock_return_t (*flock_backend_add_metadata_fn)(void*, const char*, const char*)

Add metadata to the backend.

Param void*

Pointer to the backend’s state.

Param const

char* Key (null-terminated).

Param const

char* Value (null-terminated).

typedef flock_return_t (*flock_backend_remove_metadata_fn)(void*, const char*)

Remove metadata from the backend.

Param void*

Pointer to the backend’s state.

Param const

char* Key (null-terminated).

typedef struct flock_backend_impl flock_backend_impl

Implementation of an FLOCK backend.

Functions

flock_return_t flock_register_backend(flock_backend_impl *backend_impl)

Registers a backend implementation.

Note: the backend implementation will not be copied; it is therefore important that it stays valid in memory while in use by any flock provider.

Important: up to 64 backend implementations may be registered, including the ones provided internally.

Parameters

backend_impl – backend implementation.

Returns

FLOCK_SUCCESS or error code defined in flock-common.h

struct flock_backend_init_args
#include <flock-backend.h>

Initialization arguments.

Note

The backend’s init_group can call json_object_get on the config to increase its reference count and keep it internally (the provider does not modify it).

Note

The backend’s init_group can move the initial_view internally. If it does it, it should memset the flock_backend_init_args’s initial_view field to 0 so that the provider does not free it.

Note

The provided member_update_callback and metadata_update_callback need to be called by the backend whenever a member leaves or joins, and whenever the metadata is updated, respectively. When called, these function must be passed the provided callback_context.

Note

The backend should NOT use margo_addr_self to get its own address as it may be behind a gateway. Instead, the self_addr_str field should be used. This will have been initialized to a public address by the gateway system.

Public Members

margo_instance_id mid
uint16_t provider_id
ABT_pool pool
struct json_object *config
const char *self_addr_str
bool join
flock_group_view_t initial_view
flock_membership_update_fn member_update_callback
flock_metadata_update_fn metadata_update_callback
void *callback_context
struct flock_backend_impl
#include <flock-backend.h>

Implementation of an FLOCK backend.

Public Members

const char *name
flock_backend_init_fn init_group
flock_backend_finalize_fn destroy_group
flock_backend_get_config_fn get_config
flock_backend_get_view_fn get_view
flock_backend_add_metadata_fn add_metadata
flock_backend_remove_metadata_fn remove_metadata

flock-bootstrap-mpi.h

Functions

flock_return_t flock_group_view_init_from_mpi(margo_instance_id mid, uint16_t provider_id, MPI_Comm comm, flock_group_view_t *view)

Initialize a view from an MPI communicator. This is a collective operation across the members of the communicator.

Parameters

  • mid – [in] Margo instance ID

  • provider_id – [in] Provider ID of the provider to register on the calling process.

  • comm – [in] Communicator

  • view – [out] View

Returns

FLOCK_SUCCESS or other error codes.

flock-bootstrap.h

Functions

flock_return_t flock_group_view_init_from_self(margo_instance_id mid, uint16_t provider_id, flock_group_view_t *view)

Initialize a group view with the calling process (with the specified provider ID) as the only member.

Parameters

  • mid – [in] Margo instance ID

  • provider_id – [in] Provider ID of the only member

  • view – [out] View

Returns

FLOCK_SUCCESS or other error code.

flock_return_t flock_group_view_init_from_file(const char *filename, flock_group_view_t *view)

Initialize a group view by reading it from a file.

Parameters

  • filename – [in] File containing the view

  • view – [out] View

Returns

FLOCK_SUCCESS or other error code.

flock-client.h

Defines

FLOCK_CLIENT_NULL

Typedefs

typedef struct flock_client *flock_client_t

Functions

flock_return_t flock_client_init(margo_instance_id mid, ABT_pool pool, flock_client_t *client)

Creates a FLOCK client.

Parameters

  • mid – [in] Margo instance

  • pool – [in] Pool in which to run operations such as updates

  • client – [out] FLOCK client

Returns

FLOCK_SUCCESS or error code defined in flock-common.h

flock_return_t flock_client_finalize(flock_client_t client)

Finalizes a FLOCK client.

Parameters

client – [in] FLOCK client to finalize

Returns

FLOCK_SUCCESS or error code defined in flock-common.h

flock-common.h

Defines

FLOCK_MODE_INIT_UPDATE
FLOCK_MODE_SUBSCRIBE
FLOCK_RETURN_VALUES
X(__err__, __msg__)

Error codes that can be returned by FLOCK functions.

Typedefs

typedef enum flock_update_t flock_update_t
typedef enum flock_return_t flock_return_t
typedef void (*flock_membership_update_fn)(void*, flock_update_t, const char*, uint16_t)

Type of function called when a member joins, leaves, or dies.

Param void*

User-provided context

Param flock_update_t

Update type

Param const

char* Address of the member

Param uint16_t

Provider ID of the member

typedef void (*flock_metadata_update_fn)(void*, const char*, const char*)

Type of function called when a key/value pair in the metadata of a group is updated.

Param void*

User-provided context

Param const

char* Metadata key

Param size_t

Size of the metadata key

Param const

char* Metadata value

Param size_t

Size of the metadata value

Enums

enum flock_update_t

Values:

enumerator FLOCK_MEMBER_JOINED
enumerator FLOCK_MEMBER_LEFT
enumerator FLOCK_MEMBER_DIED
enumerator FLOCK_MEMBER_MOVED
enum flock_return_t

Values:

enumerator FLOCK_RETURN_VALUES

flock-gateway.h

Typedefs

typedef struct flock_gateway_init_args flock_gateway_init_args_t

Initialization arguments.

Note

The gateway’s init_gateway can call json_object_get on the config to increase its reference count and keep it internally (the provider does not modify it).

typedef flock_return_t (*flock_gateway_init_fn)(flock_gateway_init_args_t *args, void**)

Allocates and initializes the state of a gateway.

Note

This function may move some of the fields of the flock_gateway_init_args_t (see comments about flock_gateway_init_args_t above).

Param flock_gateway_init_args_t*

[in] Initialization arguments.

Param void**

[out] Pointer to the allocated state.

typedef flock_return_t (*flock_gateway_finalize_fn)(void*)

Finalizes and deallocate the state of the gateway.

Param void*

Pointer to the backend’s state.

typedef flock_return_t (*flock_gateway_get_config_fn)(void*, void (*)(void*, const struct json_object*), void*)

Get the config of the gateway and pass it to the provided function pointer.

Param void*

Pointer to the gateway’s state.

Param void

(*)(void*, const struct json_object*) Function to call on the config.

Param void*

Context to pass to the function.

typedef const char *(*flock_gateway_get_public_address_fn)(void*)

Get the public address of this process according to the gateway.

Param void*

Pointer to the gateway’s state.

Return

const char* Public address as a null-terminated string.

typedef const char *(*flock_gateway_get_local_address_fn)(void*)

Get the local address of this process.

Param void*

Pointer to the gateway’s state.

Return

const char* Local address as a null-terminated string.

typedef struct flock_gateway_impl flock_gateway_impl

Implementation of an FLOCK gateway.

Functions

flock_return_t flock_register_gateway(flock_gateway_impl *gateway_impl)

Registers a gateway implementation.

Note: the gateway implementation will not be copied; it is therefore important that it stays valid in memory while in use by any flock provider.

Important: up to 64 gateway implementations may be registered, including the ones provided internally.

Parameters

gateway_impl – gateway implementation.

Returns

FLOCK_SUCCESS or error code defined in flock-common.h

struct flock_gateway_init_args
#include <flock-gateway.h>

Initialization arguments.

Note

The gateway’s init_gateway can call json_object_get on the config to increase its reference count and keep it internally (the provider does not modify it).

Public Members

margo_instance_id mid
uint16_t provider_id
ABT_pool pool
struct json_object *config
struct flock_gateway_impl
#include <flock-gateway.h>

Implementation of an FLOCK gateway.

Public Members

const char *name
flock_gateway_init_fn init_gateway
flock_gateway_finalize_fn destroy_gateway
flock_gateway_get_config_fn get_config
flock_gateway_get_public_address_fn get_public_address
flock_gateway_get_local_address_fn get_local_address

flock-group-view.h

This file provides the definition of the flock_flock_group_view_t structure and can be used by backend implementers. It is not meant to be used by clients.

Defines

FLOCK_GROUP_VIEW_INITIALIZER
FLOCK_GROUP_VIEW_MOVE(__src__, __dst__)

This macro takes two pointers to flock_group_view_t and moves the content of the source into the destination.

Warning

This macro assumes that the destination is empty. If it is not, it may cause a member leak as the destination looses the pointers to its data.

Parameters

  • __src__ – flock_group_view_t* from which to move.

  • __dst__ – flock_group_view_t* into which to move.

FLOCK_GROUP_VIEW_LOCK(view)
FLOCK_GROUP_VIEW_UNLOCK(view)

Functions

static inline hg_return_t hg_proc_flock_member_t(hg_proc_t proc, flock_member_t *member)

Mercury serialization/deserialization function for flock_member_t.

MERCURY_GEN_PROC (flock_metadata_t,((hg_string_t)(key))((hg_string_t)(value))) typedef struct

Key/value pair.

Will define the following structure:

typedef struct {
    char* key;
    char* value;
} flock_metadata_t;

Group view.

A group view contains a dynamic array of members (flock_member_t), a dynamic array of metadata (flock_metadata_t), a digest, and a mutex to protect access to the view’s fields.

Important: while the fields can be read without the need for the bellow flock_* functions and FLOCK_* macros, they SHOULD NOT BE MODIFIED without calling these functions/macros. This is because (1) these functions also keep the digest up-to-date when the view is modified, and (2) these functions also ensure some invariants on the content of the view, such as the fact that members are sorted by rank, ranks are unique, metadata are sorted by key, keys are unique, and so on. Any direct modification of these fields risk breaking these invariants.

static inline uint64_t flock_group_view_digest(const flock_group_view_t *view)

Return the view’s digest.

Parameters

view – View.

Returns

The view’s digest.

static inline void flock_group_view_clear(flock_group_view_t *view)

Clear the content of a flock_flock_group_view_t.

Parameters

view – Group view to clear.

static inline void flock_group_view_clear_extra(flock_group_view_t *view)

Clear the extra fields of a flock_flock_group_view_t.

Parameters

view – Group view to clear.

static inline int flock_member_cmp(flock_member_t *mem1, flock_member_t *mem2)

Lexicographic comparison between two members. First compares the provider IDs, then addresses.

Parameters

  • mem1 – Member 1

  • mem2 – Member 1

Returns

0 if the members are equal (same address and provider ID), -1 if mem1 < mem2, 1 if mem1 > mem2.

static inline ssize_t flock_group_view_members_binary_search(const flock_group_view_t *view, const char *address, uint16_t provider_id)

Binary search through the sorted array of members.

Parameters

  • view – View to search in.

  • rank – Rank to search for.

Returns

The index of the member found, or -1 if not found.

static inline uint64_t flock_djb2_hash(const char *str)

This function is used to compute string hashes to update a group view’s digest.

Parameters

str – string to hash.

Returns

a uint64_t hash.

static inline uint64_t flock_hash_member(uint16_t provider_id, const char *address)

This function is used to compute hashes to update a group view’s digest when a member is added or removed.

Parameters

  • rank – Member rank.

  • provider_id – Member provider ID.

  • address – Member address.

Returns

a uint64_t hash.

static inline uint64_t flock_hash_metadata(const char *key, const char *val)

This function is used to compute metadata hashes to update a group view’s digest when a metadata is updated.

Parameters

  • key – Key of the metadata to hash.

  • val – Value of the metadata to hash.

Returns

a uint64_t hash.

static inline flock_member_t *flock_group_view_add_member(flock_group_view_t *view, const char *address, uint16_t provider_id)

Add a member to the view.

@important The caller is responsible for checking that they are not adding a member with a rank that is already in use.

Parameters

  • view – View in which to add the member.

  • provider_id – Provider ID of the new member.

  • address – Address of the new member.

Returns

a pointer to the added flock_member_t* if successful, NULL in case of allocation error.

static inline bool flock_group_view_remove_member(flock_group_view_t *view, flock_member_t *member)

Removes a member given its rank.

@important The member pointer must point to a member inside the provided view (e.g. the member pointer can have been obtained using flock_group_view_find_member).

Parameters

  • view – View from which to remove the member.

  • member – Pointer to the member to remove.

Returns

true if the member was removed, false if it wasn’t found.

static inline flock_member_t *flock_group_view_find_member(flock_group_view_t *view, const char *address, uint16_t provider_id)

Find a member from its rank.

Parameters

  • view – View in which to search.

  • address – Address of the member to find.

  • provider_id – Provider ID of the member to find.

Returns

A pointer to the member, or NULL if not found.

static inline flock_member_t *flock_group_view_member_at(flock_group_view_t *view, size_t index)

Return the member at the specified index.

Parameters

  • view – View in which to search.

  • index – Index of the member.

Returns

A pointer to the member, or NULL if not found.

static inline size_t flock_group_view_member_count(flock_group_view_t *view)

Return the number of members in the view.

Parameters

view – View.

Returns

The number of members in the view.

static inline ssize_t flock_group_view_metadata_binary_search(const flock_group_view_t *view, const char *key)

Binary search through the sorted array of metadata entries.

Parameters

  • view – View to search in.

  • key – Key to search for.

Returns

The index of the metadata found, or -1 if not found.

static inline flock_metadata_t *flock_group_view_add_metadata(flock_group_view_t *view, const char *key, const char *value)

Add a metadata to the view. If a metadata with the same key already exists, its value will be replaced.

Parameters

  • view – View in which to add the metadata.

  • key – Key.

  • value – Value.

Returns

a pointer to a flock_metadata_t if added, NULL in case of an allocation error.

static inline bool flock_group_view_remove_metadata(flock_group_view_t *view, const char *key)

Removes a metadata given its key.

Parameters

  • view – View from which to remove the metadata.

  • rank – Key of the metadata to remove.

Returns

true if the metadata was removed, false if it wasn’t found.

static inline const char *flock_group_view_find_metadata(const flock_group_view_t *view, const char *key)

Find a metadata from its key.

Parameters

  • view – View in which to search.

  • key – Key of the metadata to find.

Returns

A pointer to the value, or NULL if not found.

static inline flock_metadata_t *flock_group_view_metadata_at(flock_group_view_t *view, size_t index)

Return the metadata at the specified index.

Parameters

  • view – View in which to search.

  • index – Index of the metadata.

Returns

A pointer to the metadata, or NULL if not found.

static inline size_t flock_group_view_metadata_count(flock_group_view_t *view)

Return the number of key/value pairs in the view.

Parameters

view – View.

Returns

The number of key/value pairs in the view.

static inline bool flock_group_view_copy(const flock_group_view_t *src, flock_group_view_t *dst)

Copy the content of a source view into an empty destination view.

This function creates a deep copy of all members and metadata from the source view into the destination view. The extra fields associated with members are not copied (they are backend-specific and not serialized).

Warning

This function assumes that the destination view is empty. If it is not, it may cause memory leaks.

Parameters

  • src – Source view to copy from.

  • dst – Destination view to copy into (must be empty).

Returns

true if the copy succeeded, false on allocation failure.

flock_return_t flock_group_view_serialize(const flock_group_view_t *v, void (*serializer)(void*, const char*, size_t), void *context)

Serialize a flock_group_view_t and pass the serialized string to a serializer function pointer.

Parameters

  • v – View to serialize.

  • serializer – Function pointer to call on the serialized group view.

  • context – User-provided arguments for the serializer.

Returns

FLOCK_SUCCESS or other error codes.

flock_return_t flock_group_view_serialize_to_file(const flock_group_view_t *v, const char *filename)

Serialize a flock_group_view_t into a file.

Parameters

  • v – View to serialize.

  • filename – Name of the file into which to serialize the view.

Returns

FLOCK_SUCCESS or other error codes.

flock_return_t flock_group_view_from_string(const char *str, size_t str_len, flock_group_view_t *view)

Initialize a group view from a string.

Parameters

  • str – [in] String containing the serialized group view.

  • str_len – [in] Length of the string.

  • view – [out] View to deserialize.

Returns

FLOCK_SUCCESS or other error codes.

flock_return_t flock_group_view_from_file(const char *filename, flock_group_view_t *view)

Initialize a group file from a file.

Parameters

  • filename – [in] File to read the view from.

  • view – [out] View to deserialize.

  • credentials – [out] Credential value.

Returns

FLOCK_SUCCESS or other error codes.

static inline hg_return_t hg_proc_flock_group_view_t(hg_proc_t proc, void *args)

Serialize/deserialize a group view.

Parameters

  • proc – Mercury proc object.

  • view – View to serialize/deserialize.

Returns

hg_return_t code.

static inline hg_return_t hg_proc_flock_protected_group_view_t(hg_proc_t proc, void *args)

Serializes/deserializes a flock_group_view_t and protect its access with a lock.

Parameters

  • proc – Mercury proc object.

  • view – View to serialize/deserialize.

Returns

hg_return_t code.

Variables

flock_group_view_t
struct flock_member_t
#include <flock-group-view.h>

Representation of a group member.

Public Members

char *address
uint16_t provider_id
void *data
void (*free)(void*)
struct flock_member_t extra

flock-group.h

Defines

FLOCK_GROUP_HANDLE_NULL

Typedefs

typedef struct flock_group_handle *flock_group_handle_t
typedef struct flock_request *flock_request_t

Handle for a non-blocking request.

Functions

flock_return_t flock_group_handle_create(flock_client_t client, hg_addr_t addr, uint16_t provider_id, uint32_t mode, flock_group_handle_t *handle)

Creates a FLOCK group handle by contacting the group member specified by the given address and provider ID.

Parameters

  • client – [in] FLOCK client responsible for the group handle

  • addr – [in] Mercury address of one of the members

  • provider_id – [in] id of the member

  • mode – [in] Optional mode

  • handle – [out] group handle

Returns

FLOCK_SUCCESS or error code defined in flock-common.h

flock_return_t flock_group_handle_create_from_file(flock_client_t client, const char *filename, uint32_t mode, flock_group_handle_t *handle)

Creates a FLOCK group handle by reading the specified file.

Note: a FLOCK group file is a JSON file with the following format. 

{
   "members": [
       { "address": "<some-address>", "provider_id": 1234 },
       ...
   ],
   "metadata": {
       "key": "value"
       ...
   }
}
The “transport” field contains the Mercury transport method used (e.g. ofi+tcp), the “credentials” field contains a credential token if communication with group members requires one. The “members” field is an array of members, each described with its address and provider ID. The “metadata” field contains any key/value pairs relevant to the group’s usage.

Parameters

  • client – [in] FLOCK client responsible for the group handle

  • filename – [in] File name of the group file

  • mode – [in] Optional mode

  • handle – [out] group handle

Returns

FLOCK_SUCCESS or error code defined in flock-common.h

flock_return_t flock_group_handle_create_from_serialized(flock_client_t client, const char *serialized_view, size_t view_size, uint32_t mode, flock_group_handle_t *handle)

Creates a FLOCK group handle from a serialized view. This serialized view must have been generated using flock_group_handle_serialize.

Parameters

  • client – [in] FLOCK client responsible for the group handle

  • addr – [in] Mercury address of the provider

  • provider_id – [in] id of the provider

  • mode – [in] Optional mode

  • handle – [out] group handle

Returns

FLOCK_SUCCESS or error code defined in flock-common.h

flock_return_t flock_group_handle_ref_incr(flock_group_handle_t handle)

Increments the reference counter of a group handle.

Parameters

handle – group handle

Returns

FLOCK_SUCCESS or error code defined in flock-common.h

flock_return_t flock_group_handle_release(flock_group_handle_t handle)

Releases the group handle. This will decrement the reference counter, and free the group handle if the reference counter reaches 0.

Parameters

handle – [in] group handle to release.

Returns

FLOCK_SUCCESS or error code defined in flock-common.h

flock_return_t flock_group_get_view(flock_group_handle_t handle, flock_group_view_t *view)

Copy the internal view. The resulting view should be freed by the caller using flock_group_view_clear.

Parameters

  • handle – [in] Group handle

  • view – [out] View

Returns

FLOCK_SUCCESS or error code defined in flock-common.h

flock_return_t flock_group_access_view(flock_group_handle_t handle, void (*access)(void *uargs, const flock_group_view_t *view), void *uargs)

Access the group’s internal view without copying it, by passing a function pointer. The view is locked until the access function returns.

Parameters

  • handle – Group handle

  • access – Access function pointer

  • uargs – Argument for the user-provided function pointer

Returns

FLOCK_SUCCESS or error code defined in flock-common.h

flock_return_t flock_group_metadata_set(flock_group_handle_t handle, const char *key, const char *value)

Send a key/value pair to be added in the metadata of the group. How this information will be propagated in the group depends on the group’s implementation. There is no guarantee that the metadata is added upon completion of this function.

Parameters

  • handle – Group handle

  • key – Key to add

  • value – Value to add

Returns

FLOCK_SUCCESS or error code defined in flock-common.h

flock_return_t flock_group_update_view(flock_group_handle_t handle, flock_request_t *req)

Update the cached, internal view of the group by contacting one (or more) of its members.

If req != NULL, the operation will be non-blocking

Parameters

  • handle – Group handle.

  • req – Optional request pointer.

Returns

FLOCK_SUCCESS or error code defined in flock-common.h

flock_return_t flock_request_wait(flock_request_t req)

Wait for completion of a request.

Parameters

req – Request to wait on.

Returns

FLOCK_SUCCESS or error code defined in flock-common.h

flock_return_t flock_request_test(flock_request_t req, bool *completed)

Test for completion of a request.

Parameters

req – Request to test.

Returns

FLOCK_SUCCESS or error code defined in flock-common.h

flock_return_t flock_group_subscribe(flock_group_handle_t handle, flock_membership_update_fn member_update_fn, flock_metadata_update_fn metadata_update_fn, void *context)

Subscribe to updates from the group. The consistency of such updates depend on the backend implementation of the group’s fault detection protocol.

@important The client’s margo_instance_id must have been initialized as a server for this functionality to be available.

Parameters

  • handle – Group handle

  • member_update_fn – Function to call when a member is updated

  • metadata_update_fn – Function to call when a metadata is updated

  • context – Context to pass to the above functions

Returns

FLOCK_SUCCESS or error code defined in flock-common.h

flock_return_t flock_group_unsubscribe(flock_group_handle_t handle)

Stop being notified about updates from this group.

Parameters

handle – Group handle

Returns

FLOCK_SUCCESS or error code defined in flock-common.h

flock-server.h

Defines

FLOCK_ABT_POOL_DEFAULT
FLOCK_PROVIDER_NULL
FLOCK_PROVIDER_IGNORE
FLOCK_PROVIDER_ARGS_INIT

Typedefs

typedef struct flock_provider *flock_provider_t

Functions

flock_return_t flock_provider_register(margo_instance_id mid, uint16_t provider_id, const char *config, const struct flock_provider_args *args, flock_provider_t *provider)

Creates a new FLOCK provider.

The config parameter must have the following format.

{
    "bootstrap": "<method>",
    "group": {
        "type": "static", // or another backend type
        "config": { ... } // backend-specific configuration
    },
    "gateway": {
        "type": "default", // or another gateway type
        "config": { ... }  // gateway-specific configuration
    },
    "file": "<path>"
}

The bootstrap method may be one of the following:

  • ”self”: the provider will form a group with only itself as the member.

  • ”view”: use args->bootstrap.initial_view as initial view of the group. All the providers in the view must be registered at the same time and with the same configuration and initial view. If different configurations or initial views are provided to each provider, the result is undefined. The provider that is being registered must be part of the initial view.

  • ”mpi”: use args->bootstrap.mpi_comm (cast to an MPI_Comm) to initialize the initial view of the group. This method will involve collective communications across processes of the specified communicator. If the mpi_comm is set to NULL, MPI_COMM_WORLD will be used by default. MPI must have been initialized for this method to work.

  • ”join”: use args->bootstrap.join_group as the group handle of an existing group that the created provider must join, or if provided.

  • ”file”: join the group represented by the group file.

Parameters

  • mid – [in] Margo instance

  • provider_id – [in] provider id

  • initial_view – [in] initial view

  • config – [in] Configuration

  • args – [in] additions arguments structure

  • provider – [out] provider

Returns

FLOCK_SUCCESS or error code defined in flock-common.h

flock_return_t flock_provider_add_update_callbacks(flock_provider_t provider, flock_membership_update_fn member_update_fn, flock_metadata_update_fn metadata_update_fn, void *context)

Register callbacks that the provider will call when a member is updated or when the metadata is changed.

Note

The context argument is what will uniquely identify this callback registration and can be used in flock_provider_remove_update_callback to deregister these callbacks. It is valid to call flock_provider_add_update_callbacks multiple times with distinct contexts.

Parameters

  • provider – Provider

  • member_update_fn – Function to call when a member is updated

  • metadata_update_fn – Function to call when a metadata is updated

  • context – Context to pass to the above functions

Returns

FLOCK_SUCCESS or error code defined in flock-common.h

flock_return_t flock_provider_remove_update_callbacks(flock_provider_t provider, void *context)

Remove the callbask associated with the given context.

Parameters

  • provider – Provider

  • context – Context

Returns

FLOCK_SUCCESS or error code defined in flock-common.h

flock_return_t flock_provider_destroy(flock_provider_t provider)

Destroys the Alpha provider and deregisters its RPC.

Parameters

provider – [in] Alpha provider

Returns

FLOCK_SUCCESS or error code defined in flock-common.h

char *flock_provider_get_config(flock_provider_t provider)

Returns a JSON-formatted configuration of the provider.

The caller is responsible for freeing the returned pointer.

Parameters

provider – Alpha provider

Returns

a heap-allocated JSON string or NULL in case of an error.

struct flock_provider_args
#include <flock-server.h>

Optional arguments to pass to the flock_provider_register function.

The pool will default to the margo_instance_id’s default handler pool.

If NULL, the initial_view will default to a view that include only the current provider, with rank set to 0. If provided, the provider will take ownership of the view’s content and reset it to empty for the caller.

If not provided, the backend will default to the type specified in the JSON configuration passed to flock_provider_register.

If not provided, the gateway will default to the type specified in the JSON configuration passed to flock_provider_register.

Public Members

ABT_pool pool
flock_group_view_t *initial_view
flock_backend_impl *backend
flock_gateway_impl *gateway