gpr.h

MPI stands for the Message Passing Interface. Written by the MPI Forum (a large committee comprising

                                                     char **keys,
                                                     orte_std_cntr_t *levels,
                                                     orte_gpr_trigger_cb_fn_t cbfunc,
                                                     void *user_tag);

/*
 * Cancel a subscription.
 * Once a subscription has been entered on the registry, a caller may choose to permanently
 * remove it at a later time. This function supports that request.
 *
 * @param sub_number The orte_gpr_subscription_id_t value returned by the original subscribe
 * command.
 *
 * @retval ORTE_SUCCESS The subscription was removed.
 * @retval ORTE_ERROR The subscription could not be removed - most likely caused by specifying
 * a non-existent (or previously removed) subscription number.
 *
 * @code
 * status_code = orte_gpr.unsubscribe(sub_number);
 * @endcode
 */
typedef int (*orte_gpr_base_module_unsubscribe_fn_t)(orte_gpr_subscription_id_t sub_number);

/*
 * Cancel a trigger.
 * Once a trigger has been entered on the registry, a caller may choose to permanently
 * remove it at a later time. This function supports that request.
 *
 * @param trig_number The orte_gpr_trigger_id_t value returned by the original subscribe
 * command.
 *
 * @retval ORTE_SUCCESS The trigger was removed.
 * @retval ORTE_ERROR The trigger could not be removed - most likely caused by specifying
 * a non-existent (or previously removed) trigger number.
 *
 * @code
 * status_code = orte_gpr.cancel_trigger(trig_number);
 * @endcode
 */
typedef int (*orte_gpr_base_module_cancel_trigger_fn_t)(orte_gpr_trigger_id_t trig_number);


/* Output the registry's contents to an output stream
 * For debugging purposes, it is helpful to be able to obtain a complete formatted printout
 * of the registry's contents. This function provides that ability.
 *
 * @param output_id The output stream id to which the registry's contents are to be
 * printed.
 *
 * @retval ORTE_SUCCESS Operation was successfully completed.
 * @retval ORTE_ERROR(s) Operation failed, returning the provided error code.
 *
 * @code
 * orte_gpr.dump(output_id);
 * @endcode
 */
typedef int (*orte_gpr_base_module_dump_all_fn_t)(void);

typedef int (*orte_gpr_base_module_dump_segment_fn_t)(char *segment);

typedef int (*orte_gpr_base_module_dump_triggers_fn_t)(
                            orte_gpr_trigger_id_t tail);

typedef int (*orte_gpr_base_module_dump_subscriptions_fn_t)(
                            orte_gpr_subscription_id_t tail);

typedef int (*orte_gpr_base_module_dump_a_trigger_fn_t)(
                            char *name,
                            orte_gpr_trigger_id_t id);

typedef int (*orte_gpr_base_module_dump_a_subscription_fn_t)(
                            char *name,
                            orte_gpr_subscription_id_t id);

typedef int (*orte_gpr_base_module_dump_local_triggers_fn_t)(void);

typedef int (*orte_gpr_base_module_dump_local_subscriptions_fn_t)(void);

typedef int (*orte_gpr_base_module_dump_callbacks_fn_t) (void);

typedef int (*orte_gpr_base_module_dump_notify_msg_fn_t)(orte_gpr_notify_message_t *msg);

typedef int (*orte_gpr_base_module_dump_notify_data_fn_t)(orte_gpr_notify_data_t *data);

typedef int (*orte_gpr_base_module_dump_value_fn_t)(orte_gpr_value_t *value);

typedef int (*orte_gpr_base_module_dump_segment_size_fn_t)(char *segment);

/*
 * Increment value
 * This function increments the stored value of an existing registry entry by one. Failure
 * to find the entry on the registry will result in an error.
 */
typedef int (*orte_gpr_base_module_increment_value_fn_t)(orte_gpr_value_t *value);

/*
 * Decrement value
 * This function decrements the stored value of an existing registry entry by one. Failure
 * to find the entry on the registry will result in an error.
 */
typedef int (*orte_gpr_base_module_decrement_value_fn_t)(orte_gpr_value_t *value);


/* Deliver a notify message
 * To support the broadcast of stage gate messages that supply all subscribed
 * data in a single message, we have to provide an API that allows the xcast
 * to "inject" the message back into the registry's local delivery system.
 *
 * @param msg A pointer to the orte_gpr_notify_message_t object to be delivered.
 * Note that the calling program is responsible for releasing this object.
 *
 * @retval None
 */
typedef int (*orte_gpr_base_module_deliver_notify_msg_t)(orte_gpr_notify_message_t *msg);


/* Create a gpr value structure
 * To make it easier for users, this function will create an orte_gpr_value_t structure,
 * including performing all the error checks to ensure adequate memory is available.
 *
 * Any data that the caller wishes to provide will be pre-loaded into the returned value.
 * The function will allocate space for the value object and for the number of keyvals
 * and tokens to be stored in the object. If the caller wishes to allocate that space
 * themselves, or does not want space allocated for those purposes, then just pass a
 * value of "0" (zero) and the function will not allocate memory to those areas. Likewise,
 * a value of NULL for segment will cause the function to ignore that field in the
 * value object.
 *
 * @retval ORTE_SUCCESS Value structure successfully created
 * @retval ORTE_XXXX Appropriate error code indicating problem encountered.
 */
typedef int (*orte_gpr_base_module_create_value_fn_t)(orte_gpr_value_t **value,
                                                orte_gpr_addr_mode_t addr_mode,
                                                char *segment,
                                                orte_std_cntr_t cnt,  /**< Number of keyval objects */
                                                orte_std_cntr_t num_tokens);
/* Create a keyval object
 * To make it easier for users, this function will create an orte_gpr_keyval_t object,
 * including performing all the error checks to ensure adequate memory is available.
 *
 * Any data that the caller provides will be copied into the returned keyval object.
 * If key or data are set to NULL, then those fields will be left to their default NULL
 * values.
 *
 * @retval ORTE_SUCCESS Value structure successfully created
 * @retval ORTE_XXXX Appropriate error code indicating problem encountered.
 */
typedef int (*orte_gpr_base_module_create_keyval_fn_t)(orte_gpr_keyval_t **keyval,
                                                 char *key,
                                                 orte_data_type_t type,
                                                 void *data);
/*
 * Ver 1.0.0
 */
struct orte_gpr_base_module_1_0_0_t {
    /* INIT */
    orte_gpr_base_module_init_fn_t init;
    /* BLOCKING OPERATIONS */
    orte_gpr_base_module_get_fn_t get;
    orte_gpr_base_module_get_conditional_fn_t get_conditional;
    orte_gpr_base_module_put_fn_t put;
    orte_gpr_base_module_put_1_fn_t put_1;
    orte_gpr_base_module_put_N_fn_t put_N;
    orte_gpr_base_module_delete_entries_fn_t delete_entries;
    orte_gpr_base_module_delete_segment_fn_t delete_segment;
    orte_gpr_base_module_index_fn_t index;
    /* NON-BLOCKING OPERATIONS */
    orte_gpr_base_module_get_nb_fn_t get_nb;
    orte_gpr_base_module_put_nb_fn_t put_nb;
    orte_gpr_base_module_delete_entries_nb_fn_t delete_entries_nb;
    orte_gpr_base_module_delete_segment_nb_fn_t delete_segment_nb;
    orte_gpr_base_module_index_nb_fn_t index_nb;
    /* GENERAL OPERATIONS */
    orte_gpr_base_module_create_value_fn_t create_value;
    orte_gpr_base_module_create_keyval_fn_t create_keyval;
    orte_gpr_base_module_preallocate_segment_fn_t preallocate_segment;
    orte_gpr_base_module_deliver_notify_msg_t deliver_notify_msg;
    /* ARITHMETIC OPERATIONS */
    orte_gpr_base_module_increment_value_fn_t increment_value;
    orte_gpr_base_module_decrement_value_fn_t decrement_value;
    /* SUBSCRIBE OPERATIONS */
    orte_gpr_base_module_subscribe_fn_t subscribe;
    orte_gpr_base_module_subscribe_1_fn_t subscribe_1;
    orte_gpr_base_module_subscribe_N_fn_t subscribe_N;
    orte_gpr_base_module_define_trigger_fn_t define_trigger;
    orte_gpr_base_module_define_trigger_level_fn_t define_trigger_level;
    orte_gpr_base_module_unsubscribe_fn_t unsubscribe;
    orte_gpr_base_module_cancel_trigger_fn_t cancel_trigger;
    /* COMPOUND COMMANDS */
    orte_gpr_base_module_begin_compound_cmd_fn_t begin_compound_cmd;
    orte_gpr_base_module_stop_compound_cmd_fn_t stop_compound_cmd;
    orte_gpr_base_module_exec_compound_cmd_fn_t exec_compound_cmd;
    /* DIAGNOSTIC OPERATIONS */
    orte_gpr_base_module_dump_all_fn_t dump_all;
    orte_gpr_base_module_dump_segment_fn_t dump_segment;
    orte_gpr_base_module_dump_triggers_fn_t dump_triggers;
    orte_gpr_base_module_dump_subscriptions_fn_t dump_subscriptions;
    orte_gpr_base_module_dump_a_trigger_fn_t dump_a_trigger;
    orte_gpr_base_module_dump_a_subscription_fn_t dump_a_subscription;
    orte_gpr_base_module_dump_local_triggers_fn_t dump_local_triggers;
    orte_gpr_base_module_dump_local_subscriptions_fn_t dump_local_subscriptions;
    orte_gpr_base_module_dump_callbacks_fn_t dump_callbacks;
    orte_gpr_base_module_dump_notify_msg_fn_t dump_notify_msg;
    orte_gpr_base_module_dump_notify_data_fn_t dump_notify_data;
    orte_gpr_base_module_dump_value_fn_t dump_value;
    orte_gpr_base_module_dump_segment_size_fn_t dump_segment_size;
    /* CLEANUP OPERATIONS */
    orte_gpr_base_module_cleanup_job_fn_t cleanup_job;
    orte_gpr_base_module_cleanup_proc_fn_t cleanup_process;
};
typedef struct orte_gpr_base_module_1_0_0_t orte_gpr_base_module_1_0_0_t;
typedef orte_gpr_base_module_1_0_0_t orte_gpr_base_module_t;

/*
 * GPR Component
 */

typedef orte_gpr_base_module_t* (*orte_gpr_base_component_init_fn_t)(
                                   bool *allow_multi_user_threads,
                                   bool *have_hidden_threads,
                                   int *priority);

typedef int (*orte_gpr_base_component_finalize_fn_t)(void);

/*
 * the standard component data structure
 */


struct mca_gpr_base_component_1_0_0_t {
    mca_base_component_t gpr_version;
    mca_base_component_data_1_0_0_t gpr_data;

    orte_gpr_base_component_init_fn_t gpr_init;
    orte_gpr_base_component_finalize_fn_t gpr_finalize;
};
typedef struct mca_gpr_base_component_1_0_0_t mca_gpr_base_component_1_0_0_t;
typedef mca_gpr_base_component_1_0_0_t mca_gpr_base_component_t;

/*
 * Macro for use in modules that are of type gpr v1.0.0
 */
#define MCA_GPR_BASE_VERSION_1_0_0      \
    /* gpr v1.0 is chained to MCA v1.0 */   \
    MCA_BASE_VERSION_1_0_0,         \
    /* gpr v1.0 */              \
    "gpr", 1, 0, 0

/*
 * global module that holds function pointers
 */
ORTE_DECLSPEC extern orte_gpr_base_module_t orte_gpr; /* holds selected module's function pointers */

#if defined(c_plusplus) || defined(__cplusplus)
}
#endif

#endif