Chapter 14
C Admin API

14.1 Operations

14.1.1 read_only

Change the cluster to and from read-only mode. Definition:

    int64_t  hyperdex_admin_read_only(struct hyperdex_admin* admin,
                    int ro,
                    enum hyperdex_admin_returncode* status);

Parameters:

• struct hyperdex_admin* admin
  The HyperDex admin connection to use for the operation.
• int ro
  Flag indicating whether the cluster is set to read-only mode or read-write mode. Set to non-zero for read-only mode, and zero for read-write mode.

Returns:

• enum hyperdex_admin_returncode* status
  The status of the operation. The admin library will fill in this variable before returning this operation’s request id from hyperdex_admin_loop. The pointer must remain valid until the operation completes, and the pointer should not be aliased to the status for any other outstanding operation.

14.1.2 wait_until_stable

Wait until the cluster is stable. The cluster is considered stable when all servers acknowledge the current configuration, and all initiated in previous configurations complete. Definition:

    int64_t  hyperdex_admin_wait_until_stable(struct hyperdex_admin* admin,
                    enum hyperdex_admin_returncode* status);

Parameters:

• struct hyperdex_admin* admin
  The HyperDex admin connection to use for the operation.

Returns:

• enum hyperdex_admin_returncode* status
  The status of the operation. The admin library will fill in this variable before returning this operation’s request id from hyperdex_admin_loop. The pointer must remain valid until the operation completes, and the pointer should not be aliased to the status for any other outstanding operation.

14.1.3 fault_tolerance

Change the fault tolerance of space to the specified fault tolerance threshold. Definition:

    int64_t  hyperdex_admin_fault_tolerance(struct hyperdex_admin* admin,
                    const  char* space,
                    uint64_t ft,
                    enum hyperdex_admin_returncode* status);

Parameters:

• struct hyperdex_admin* admin
  The HyperDex admin connection to use for the operation.
• const char* space
  The name of an existing space.
• uint64_t ft
  The fault-tolerance threshold. HyperDex will deploy at least one more server than this threshold to ensure that this many servers may simultaneously fail without introducing data loss or downtime.

Returns:

• enum hyperdex_admin_returncode* status
  The status of the operation. The admin library will fill in this variable before returning this operation’s request id from hyperdex_admin_loop. The pointer must remain valid until the operation completes, and the pointer should not be aliased to the status for any other outstanding operation.

14.1.4 validate_space

Validate the provided space description. Definition:

    int  hyperdex_admin_validate_space(struct hyperdex_admin* admin,
                    const  char* description,
                    enum hyperdex_admin_returncode* status);

Parameters:

• struct hyperdex_admin* admin
  The HyperDex admin connection to use for the operation.
• const char* description
  A complete space description.

Returns:

• enum hyperdex_admin_returncode* status
  The status of the operation. The admin library will fill in this variable before returning this operation’s request id from hyperdex_admin_loop. The pointer must remain valid until the operation completes, and the pointer should not be aliased to the status for any other outstanding operation.

14.1.5 add_space

Add a new space to the cluster, using the provided space description. Definition:

    int64_t  hyperdex_admin_add_space(struct hyperdex_admin* admin,
                    const  char* description,
                    enum hyperdex_admin_returncode* status);

Parameters:

• struct hyperdex_admin* admin
  The HyperDex admin connection to use for the operation.
• const char* description
  A complete space description.

Returns:

• enum hyperdex_admin_returncode* status
  The status of the operation. The admin library will fill in this variable before returning this operation’s request id from hyperdex_admin_loop. The pointer must remain valid until the operation completes, and the pointer should not be aliased to the status for any other outstanding operation.

14.1.6 rm_space

Remove space from the configuration and make it inaccessible to future operations. Definition:

    int64_t  hyperdex_admin_rm_space(struct hyperdex_admin* admin,
                    const  char* space,
                    enum hyperdex_admin_returncode* status);

Parameters:

• struct hyperdex_admin* admin
  The HyperDex admin connection to use for the operation.
• const char* space
  The name of an existing space.

Returns:

• enum hyperdex_admin_returncode* status
  The status of the operation. The admin library will fill in this variable before returning this operation’s request id from hyperdex_admin_loop. The pointer must remain valid until the operation completes, and the pointer should not be aliased to the status for any other outstanding operation.

14.1.7 mv_space

Move space from name source to name target. This is a metadata operation and has the same cost as add_space, even for populated spaces. Definition:

    int64_t  hyperdex_admin_mv_space(struct hyperdex_admin* admin,
                    const  char* source,
                    const  char* target,
                    enum hyperdex_admin_returncode* status);

Parameters:

• struct hyperdex_admin* admin
  The HyperDex admin connection to use for the operation.
• const char* source
  The name of the existing space.
• const char* target
  The new name for the space.

Returns:

• enum hyperdex_admin_returncode* status
  The status of the operation. The admin library will fill in this variable before returning this operation’s request id from hyperdex_admin_loop. The pointer must remain valid until the operation completes, and the pointer should not be aliased to the status for any other outstanding operation.

14.1.8 list_spaces

List all spaces held by the cluster. Definition:

    int64_t  hyperdex_admin_list_spaces(struct hyperdex_admin* admin,
                    enum hyperdex_admin_returncode* status,
                    const  char** spaces);

Parameters:

• struct hyperdex_admin* admin
  The HyperDex admin connection to use for the operation.

Returns:

• enum hyperdex_admin_returncode* status
  The status of the operation. The admin library will fill in this variable before returning this operation’s request id from hyperdex_admin_loop. The pointer must remain valid until the operation completes, and the pointer should not be aliased to the status for any other outstanding operation.
• const char** spaces
  A list of spaces created within the cluster. The list is a multi-line C-string with one space per line. The C-string is valid until the next call into the admin library, and will automatically be freed by the library. It should not be changed or freed by the library user.

14.1.9 list_indices

XXX Definition:

    int64_t  hyperdex_admin_list_indices(struct hyperdex_admin* admin,
                    const  char* space,
                    enum hyperdex_admin_returncode* status,
                    const  char** indexes);

Parameters:

• struct hyperdex_admin* admin
  The HyperDex admin connection to use for the operation.
• const char* space
  The name of an existing space.

Returns:

• enum hyperdex_admin_returncode* status
  The status of the operation. The admin library will fill in this variable before returning this operation’s request id from hyperdex_admin_loop. The pointer must remain valid until the operation completes, and the pointer should not be aliased to the status for any other outstanding operation.
• const char** indexes
  XXX

14.1.10 list_subspaces

XXX Definition:

    int64_t  hyperdex_admin_list_subspaces(struct hyperdex_admin* admin,
                    const  char* space,
                    enum hyperdex_admin_returncode* status,
                    const  char** subspaces);

Parameters:

• struct hyperdex_admin* admin
  The HyperDex admin connection to use for the operation.
• const char* space
  The name of an existing space.

Returns:

• enum hyperdex_admin_returncode* status
  The status of the operation. The admin library will fill in this variable before returning this operation’s request id from hyperdex_admin_loop. The pointer must remain valid until the operation completes, and the pointer should not be aliased to the status for any other outstanding operation.
• const char** subspaces
  XXX

14.1.11 add_index

Add a new index on a HyperDex attribute or document Definition:

    int64_t  hyperdex_admin_add_index(struct hyperdex_admin* admin,
                    const  char* space,
                    const  char* attribute,
                    enum hyperdex_admin_returncode* status);

Parameters:

• struct hyperdex_admin* admin
  The HyperDex admin connection to use for the operation.
• const char* space
  The name of an existing space.
• const char* attribute
  The name of an attribute or document.

Returns:

• enum hyperdex_admin_returncode* status
  The status of the operation. The admin library will fill in this variable before returning this operation’s request id from hyperdex_admin_loop. The pointer must remain valid until the operation completes, and the pointer should not be aliased to the status for any other outstanding operation.

14.1.12 rm_index

Remove an existing index Definition:

    int64_t  hyperdex_admin_rm_index(struct hyperdex_admin* admin,
                    uint64_t idxid,
                    enum hyperdex_admin_returncode* status);

Parameters:

• struct hyperdex_admin* admin
  The HyperDex admin connection to use for the operation.
• uint64_t idxid
  The index’s unique identifier. This will be an integer that identifies the index across the lifetime of the cluster.

Returns:

• enum hyperdex_admin_returncode* status
  The status of the operation. The admin library will fill in this variable before returning this operation’s request id from hyperdex_admin_loop. The pointer must remain valid until the operation completes, and the pointer should not be aliased to the status for any other outstanding operation.

14.1.13 server_register

Manually register a new server with token bound to address. Definition:

    int64_t  hyperdex_admin_server_register(struct hyperdex_admin* admin,
                    uint64_t token,
                    const  char* address,
                    enum hyperdex_admin_returncode* status);

Parameters:

• struct hyperdex_admin* admin
  The HyperDex admin connection to use for the operation.
• uint64_t token
  The server’s token which uniquely identifies the server. This will be logged by the server with the message prefix “generated new random token”, and is available via the administration tools that can introspect the cluster state.
• const char* address
  An IP/port pair to which the server is bound, specified as a human-readable c-string. For instance, 127.0.0.1:2012 specifies localhost port 2012.

Returns:

• enum hyperdex_admin_returncode* status
  The status of the operation. The admin library will fill in this variable before returning this operation’s request id from hyperdex_admin_loop. The pointer must remain valid until the operation completes, and the pointer should not be aliased to the status for any other outstanding operation.

14.1.14 server_online

Manually set server token to state AVAILABLE. Definition:

    int64_t  hyperdex_admin_server_online(struct hyperdex_admin* admin,
                    uint64_t token,
                    enum hyperdex_admin_returncode* status);

Parameters:

• struct hyperdex_admin* admin
  The HyperDex admin connection to use for the operation.
• uint64_t token
  The server’s token which uniquely identifies the server. This will be logged by the server with the message prefix “generated new random token”, and is available via the administration tools that can introspect the cluster state.

Returns:

• enum hyperdex_admin_returncode* status
  The status of the operation. The admin library will fill in this variable before returning this operation’s request id from hyperdex_admin_loop. The pointer must remain valid until the operation completes, and the pointer should not be aliased to the status for any other outstanding operation.

14.1.15 server_offline

Manually mark server token as OFFLINE. Definition:

    int64_t  hyperdex_admin_server_offline(struct hyperdex_admin* admin,
                    uint64_t token,
                    enum hyperdex_admin_returncode* status);

Parameters:

• struct hyperdex_admin* admin
  The HyperDex admin connection to use for the operation.
• uint64_t token
  The server’s token which uniquely identifies the server. This will be logged by the server with the message prefix “generated new random token”, and is available via the administration tools that can introspect the cluster state.

Returns:

• enum hyperdex_admin_returncode* status
  The status of the operation. The admin library will fill in this variable before returning this operation’s request id from hyperdex_admin_loop. The pointer must remain valid until the operation completes, and the pointer should not be aliased to the status for any other outstanding operation.

14.1.16 server_forget

Completely remove all state associated token from the cluster. Definition:

    int64_t  hyperdex_admin_server_forget(struct hyperdex_admin* admin,
                    uint64_t token,
                    enum hyperdex_admin_returncode* status);

Parameters:

• struct hyperdex_admin* admin
  The HyperDex admin connection to use for the operation.
• uint64_t token
  The server’s token which uniquely identifies the server. This will be logged by the server with the message prefix “generated new random token”, and is available via the administration tools that can introspect the cluster state.

Returns:

• enum hyperdex_admin_returncode* status
  The status of the operation. The admin library will fill in this variable before returning this operation’s request id from hyperdex_admin_loop. The pointer must remain valid until the operation completes, and the pointer should not be aliased to the status for any other outstanding operation.

14.1.17 server_kill

Manually change server token into the KILLED state. Definition:

    int64_t  hyperdex_admin_server_kill(struct hyperdex_admin* admin,
                    uint64_t token,
                    enum hyperdex_admin_returncode* status);

Parameters:

• struct hyperdex_admin* admin
  The HyperDex admin connection to use for the operation.
• uint64_t token
  The server’s token which uniquely identifies the server. This will be logged by the server with the message prefix “generated new random token”, and is available via the administration tools that can introspect the cluster state.

Returns:

• enum hyperdex_admin_returncode* status
  The status of the operation. The admin library will fill in this variable before returning this operation’s request id from hyperdex_admin_loop. The pointer must remain valid until the operation completes, and the pointer should not be aliased to the status for any other outstanding operation.

14.1.18 backup

Initiate a cluster-wide backup named backup. This has the same behavior as the hyperdex backup command discussed in Chapter 10. Definition:

    int64_t  hyperdex_admin_backup(struct hyperdex_admin* admin,
                    const  char* backup,
                    enum hyperdex_admin_returncode* status,
                    const  char** backups);

Parameters:

• struct hyperdex_admin* admin
  The HyperDex admin connection to use for the operation.
• const char* backup
  The name for the backup created by this operation.

Returns:

• enum hyperdex_admin_returncode* status
  The status of the operation. The admin library will fill in this variable before returning this operation’s request id from hyperdex_admin_loop. The pointer must remain valid until the operation completes, and the pointer should not be aliased to the status for any other outstanding operation.
• const char** backups
  A list of servers that were backed up. The list is a C-string with lines of the form “<token> <IP address> <path>”. The C-string is valid until the next call into the admin library, and will automatically be freed by the library. It should not be changed or freed by the library user.

14.1.19 enable_perf_counters

Start collecting performance counters from all servers in the cluster. Definition:

    int64_t  hyperdex_admin_enable_perf_counters(struct hyperdex_admin* admin,
                    enum hyperdex_admin_returncode* status,
                    struct hyperdex_admin_perf_counter* pc);

Parameters:

• struct hyperdex_admin* admin
  The HyperDex admin connection to use for the operation.

Returns:

• enum hyperdex_admin_returncode* status
  The status of the operation. The admin library will fill in this variable before returning this operation’s request id from hyperdex_admin_loop. The pointer must remain valid until the operation completes, and the pointer should not be aliased to the status for any other outstanding operation.
• struct hyperdex_admin_perf_counter* pc
  A struct where the admin library can store returned performance counters. Memory regions returned via the struct will be valid until the next call into the admin library and are managed by the library. They should not be freed by the user.

  Only one performance counter may be enabled at a time. Consecutive calls to enable_perf_counters will return the same ID as the previous call, and will return performance counters via the previously-used struct. To change the structure used for returning performance counters, first disable the performance counters and then re-enable them.

14.1.20 disable_perf_counters

Stop collecting performance counters from all servers in the cluster. Definition:

    void  hyperdex_admin_disable_perf_counters(struct hyperdex_admin* admin);

Parameters:

• struct hyperdex_admin* admin
  The HyperDex admin connection to use for the operation.

Returns: Nothing