gpr.h

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

                                               char *segment, char **tokens,
                                               orte_std_cntr_t n, char **keys,
                                               orte_data_value_t **data_values);


/*
 * Put data on the registry (NON-BLOCKING)
 * A non-blocking version of put.
 */
typedef int (*orte_gpr_base_module_put_nb_fn_t)(orte_std_cntr_t cnt, orte_gpr_value_t **values,
                      orte_gpr_notify_cb_fn_t cbfunc, void *user_tag);


/*
 * Get data from the registry (BLOCKING)
 * Returns data from the registry. Given an addressing mode, segment name, and a set
 * of tokens describing the data to be retrieved, the "get" function will search the specified
 * registry segment and return all data items that "match" the description. Addressing
 * modes specify how the provided tokens are to be combined to determine the match -
 * a value of "ORTE_REGISTRY_AND", for example, indictates that all the tokens must be
 * included in the object's description, but allows for other tokens to also be present.
 * A value of "ORTE_REGISTRY_XAND", in contrast, requires that all the tokens be present,
 * and that ONLY those tokens be present.
 *
 * The data is returned as a list of orte_gpr_value_t objects. The caller is
 * responsible for freeing this data storage. Only copies of the registry data are
 * returned - thus, any actions taken by the caller will NOT impact data stored on the
 * registry.
 *
 * @param addr_mode (IN) The addressing mode to be used in the search.
 * @param *segment (IN) A character string indicating the name of the segment to be searched.
 * @param **tokens (IN) A NULL-terminated **char list of tokens describing the objects to be
 * returned. A value of NULL indicates that ALL data on the segment is to be returned.
 * @param **keys (IN) A NULL-terminated **char array of keys describing the specific
 * key-value data to be returned. A value of NULL indicates that ALL key-value pairs
 * described by the segment/token combination are to be returned.
 *
 * @param *cnt (OUT) A pointer to the number of objects returned by the request.
 * @param ***values (OUT) A pointer to an array of orte_gpr_value_t object pointers
 * containing the data
 * returned by the specified search, including the segment and container id info
 * for each keyval pair.
 *
 * @retval ORTE_SUCCESS Operation was successfully completed.
 * @retval ORTE_ERROR(s) Operation failed, returning the provided error code.
 *
 * @code
 * opal_list_t *keyval_list;
 * orte_std_cntr_t cnt;
 * orte_gpr_value_t **values;
 *
 * status_code = orte_gpr.get(addr_mode, segment, tokens, keyval_list,
 *                            &cnt, &values);
 * @endcode
 */
typedef int (*orte_gpr_base_module_get_fn_t)(orte_gpr_addr_mode_t addr_mode,
                                char *segment, char **tokens, char **keys,
                                orte_std_cntr_t *cnt, orte_gpr_value_t ***values);

typedef int (*orte_gpr_base_module_get_conditional_fn_t)(orte_gpr_addr_mode_t addr_mode,
                                char *segment, char **tokens, char **keys,
                                orte_std_cntr_t num_conditions, orte_gpr_keyval_t **conditions,
                                orte_std_cntr_t *cnt, orte_gpr_value_t ***values);

/*
 * Get data from the registry (NON-BLOCKING)
 * A non-blocking version of get. Data is returned to the callback function in the
 * notify message format.
 */
typedef int (*orte_gpr_base_module_get_nb_fn_t)(orte_gpr_addr_mode_t addr_mode,
                                char *segment, char **tokens, char **keys,
                                orte_gpr_notify_cb_fn_t cbfunc, void *user_tag);


/*
 * Delete an object from the registry (BLOCKING)
 * Remove an object from the registry. Given an addressing mode, segment name, and a set
 * of tokens describing the data object, the function will search the specified
 * registry segment and delete all data items that "match" the description. Addressing
 * modes specify how the provided tokens are to be combined to determine the match -
 * a value of "ORTE_REGISTRY_AND", for example, indictates that all the tokens must be
 * included in the object's description, but allows for other tokens to also be present.
 * A value of "ORTE_REGISTRY_XAND", in contrast, requires that all the tokens be present,
 * and that ONLY those tokens be present.
 *
 * Note: A value of NULL for the tokens will delete ALL data items from the specified
 * segment.
 *
 * @param addr_mode The addressing mode to be used in the search.
 * @param *segment A character string indicating the name of the segment to be searched.
 * @param **tokens A NULL-terminated **char list of tokens describing the objects to be
 * returned. A value of NULL indicates that ALL data on the segment is to be removed.
 *
 * @retval ORTE_SUCCESS Operation was successfully completed.
 * @retval ORTE_ERROR(s) Operation failed, returning the provided error code.
 *
 * @code
 * status_code = orte_gpr.delete_object(mode, segment, tokens);
 * @endcode
 */
typedef int (*orte_gpr_base_module_delete_entries_fn_t)(orte_gpr_addr_mode_t addr_mode,
                              char *segment, char **tokens, char **keys);

/*
 * Delete an object from the registry (NON-BLOCKING)
 * A non-blocking version of delete object. Result of the command is returned
 * to the callback function in the notify msg format.
 */
typedef int (*orte_gpr_base_module_delete_entries_nb_fn_t)(
                            orte_gpr_addr_mode_t addr_mode,
                            char *segment, char **tokens, char **keys,
                            orte_gpr_notify_cb_fn_t cbfunc, void *user_tag);
/*
 * Obtain an index of a specified dictionary (BLOCKING)
 * The registry contains a dictionary at the global level (containing names of all the
 * segments) and a dictionary for each segment (containing the names of all tokens used
 * in that segment). This command allows the caller to obtain a list of all entries
 * in the specified dictionary.
 *
 * @param *segment (IN) A character string indicating the segment whose dictionary is to be
 * indexed. A value of NULL indicates that the global level dictionary is to be used.
 *
 * @param *cnt (IN) A pointer to a orte_std_cntr_t location for storing the number of
 * tokens in the index.
 * @param ***index (IN) The address to place a char** array of strings containing an
 * index of the specified dictionary.
 *
 * @retval ORTE_SUCCESS Operation was successfully completed.
 * @retval ORTE_ERROR(s) Operation failed, returning the provided error code.
 *
 * @code
 * int32_t cnt;
 * char *index;
 * char *segment;
 *
 * status_code = orte_gpr.index(segment, &cnt, &index);
 * @endcode
 */
typedef int (*orte_gpr_base_module_index_fn_t)(char *segment, orte_std_cntr_t *cnt, char ***index);

/*
 * Obtain an index of a specified dictionary (NON-BLOCKING)
 * A non-blocking version of index. Result of the command is returned to the
 * callback function in the notify msg format.
 */
typedef int (*orte_gpr_base_module_index_nb_fn_t)(char *segment,
                        orte_gpr_notify_cb_fn_t cbfunc, void *user_tag);

/*
 * Subscribe to be notified upon a specified action
 * The registry includes a publish/subscribe mechanism by which callers can be notified
 * upon certain actions occuring to data objects stored on the registry. This function
 * allows the caller to register for such notifications. The registry allows a subscription
 * to be placed upon any segment, and upon the entire registry if desired.
 *
 * Two types of subscriptions are supported:
 * (a) notifications - these occur whenever the specified action occurs on the
 * identified data entries in the registry.
 *
 * (b) triggers - these occur whenever a count of the number of identified data
 * entries reaches the specified level. The caller can specify that the trigger
 * maintain its own count - in this case, the trigger will count the number of data
 * entries in the registry that meet the specifications provided in \em value, and store
 * the running count in the location specified by \em trig_value. Alternatively, the
 * caller can specify that the trigger only monitor a count that is being maintained
 * by someone else - in this case, the \em trig_value information is used to identify
 * one or more "counters" that are to be monitored, with the trigger fired when either all
 * identified counters reach the respective levels provided in \em trig_value (using
 * the AT mode) or when the levels reach the same value (the CMP mode).
 *
 * Note that all addressing mode rules apply to both \em value and \em trig_value,
 * including wildcards.
 *
 * @param actions (IN) The actions which are to generate a notification message and/or define
 * the trigger operation. These can
 * be OR'd together from the defined registry action flags.
 *
 * @param num_subs (IN) The numbr of subscription objects being provided
 *
 * @param **subscriptions (IN) A pointer to an array of subscription objects that
 * contain descriptions of the data that is to be returned when a subscription fires.
 * For subscribe requests that do NOT include a trigger, this is the data that
 * will be monitored per the specified action. All of
 * the described values will be returned in a notification message when the specified
 * action occurs.
 *
 * @param num_trigs (IN) The number of trigger objects being provided
 *
 * @param **triggers (IN) A pointer to an array of orte_gpr_trigger_t objects that describe the
 * conditions (as described above) which will generate a trigger message to be sent
 * to the callback function. Trigger messages include all data specified in the
 * subscription objects, but do NOT include the trigger counters themselves unless
 * so specified with the ORTE_GPR_TRIG_INCLUDE_DATA command.
 *
 * @param *sub_number (OUT) The notify id for the resulting subscription
 * is returned in the provided memory location. Callers should save this
 * number for later use if (for example) it is desired to remove the
 * subscription from the registry
 *
 * @retval ORTE_SUCCESS Operation was successfully completed.
 * @retval ORTE_ERROR(s) Operation failed, returning the provided error code.
 *
 * @code
 * orte_gpr_subscription_t *subscription;
 * orte_gpr_notify_id_t sub_number;
 * orte_gpr_value_t trig_value;
 *
 * status_code = orte_gpr.subscribe(action, 1, &subscription, &trig_value,
 *                                       &sub_number);
 * @endcode
 */
typedef int (*orte_gpr_base_module_subscribe_fn_t)(
                            orte_std_cntr_t num_subs,
                            orte_gpr_subscription_t **subscriptions,
                            orte_std_cntr_t num_trigs,
                            orte_gpr_trigger_t **triggers);

/* simplified subscription functions */
typedef int (*orte_gpr_base_module_subscribe_1_fn_t)(orte_gpr_subscription_id_t *id,
                                                     char *trig_name,
                                                     char *sub_name,
                                                     orte_gpr_notify_action_t action,
                                                     orte_gpr_addr_mode_t addr_mode,
                                                     char *segment,
                                                     char **tokens,
                                                     char *key,
                                                     orte_gpr_notify_cb_fn_t cbfunc,
                                                     void *user_tag);

typedef int (*orte_gpr_base_module_subscribe_N_fn_t)(orte_gpr_subscription_id_t *id,
                                                     char *trig_name,
                                                     char *sub_name,
                                                     orte_gpr_notify_action_t action,
                                                     orte_gpr_addr_mode_t addr_mode,
                                                     char *segment,
                                                     char **tokens,
                                                     orte_std_cntr_t n,
                                                     char **keys,
                                                     orte_gpr_notify_cb_fn_t cbfunc,
                                                     void *user_tag);

typedef int (*orte_gpr_base_module_define_trigger_fn_t)(orte_gpr_trigger_id_t *id,
                                                     char *trig_name,
                                                     orte_gpr_trigger_action_t action,
                                                     orte_gpr_addr_mode_t addr_mode,
                                                     char *segment,
                                                     char **tokens,
                                                     orte_std_cntr_t n,
                                                     char **keys,
                                                     orte_gpr_trigger_cb_fn_t cbfunc,
                                                     void *user_tag);

typedef int (*orte_gpr_base_module_define_trigger_level_fn_t)(orte_gpr_trigger_id_t *id,
                                                     char *trig_name,
                                                     orte_gpr_trigger_action_t action,
                                                     orte_gpr_addr_mode_t addr_mode,
                                                     char *segment,
                                                     char **tokens,
                                                     orte_std_cntr_t n,