base.h

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

/*
 * Copyright (c) 2004-2005 The Trustees of Indiana University and Indiana
 *                         University Research and Technology
 *                         Corporation.  All rights reserved.
 * Copyright (c) 2004-2006 The University of Tennessee and The University
 *                         of Tennessee Research Foundation.  All rights
 *                         reserved.
 * Copyright (c) 2004-2005 High Performance Computing Center Stuttgart,
 *                         University of Stuttgart.  All rights reserved.
 * Copyright (c) 2004-2005 The Regents of the University of California.
 *                         All rights reserved.
 * $COPYRIGHT$
 *
 * Additional copyrights may follow
 *
 * $HEADER$
 */
/** @file:
 *
 * The Open MPI general purpose registry.
 *
 * The Open MPI system contains a general purpose registry for use by both
 * applications and internal systems to dynamically share information. For
 * speed purposes, the registry is divided into "segments", each labelled
 * with an appropriate "token" string that describes its contents. Segments
 * are automatically provided for the "universe" and for each MPI CommWorld.
 * At this time, all segments may be accessed by any application within the universe, thus
 * providing a mechanism for cross-CommWorld communications (with the requirement
 * that all participating CommWorlds must reside within the same universe). In the future,
 * some form of security may be provided to limit access privileges between
 * segments.
 *
 * Within each registry segment, there exists a list of objects that have
 * been "put" onto the registry. Each object must be tagged with at least
 * one token, but may be tagged with as many tokens as the creator desires.
 * Retrieval requests must specify the segment and at least one token, but
 * can specify an arbitrary number of tokens to describe the search. The registry
 * will return a list of all objects that meet the search criteria.
 *
 * Tokens are defined as character strings, thus allowing for clarity in
 * the program. However, for speed purposes, tokens are translated into
 * integer keys prior to storing an object. A table of token-key pairs
 * is independently maintained for each registry segment. Users can obtain
 * an index of tokens within a dictionary by requesting it through the orte_registry_index()
 * function.
 *
 * The registry also provides a subscription capability whereby a caller
 * can subscribe to a stored object and receive notification when various actions
 * are performed on that object. Currently supported actions include modification,
 * the addition of another subscriber, and deletion. Notifications are sent via
 * the OOB communication channel.
 *
 *
 */

#ifndef ORTE_GPR_BASE_H_
#define ORTE_GPR_BASE_H_

/*
 * includes
 */
#include "orte_config.h"

#include "orte/orte_constants.h"
#include "orte/orte_types.h"

#include "opal/class/opal_list.h"
#include "orte/dss/dss_types.h"

#include "opal/mca/mca.h"
#include "opal/mca/base/base.h"
#include "opal/mca/base/mca_base_param.h"
#include "orte/mca/rml/rml_types.h"

#include "orte/mca/gpr/gpr.h"

/*
 * Global functions for MCA overall collective open and close
 */
#if defined(c_plusplus) || defined(__cplusplus)
extern "C" {
#endif

/*
 * Define flag values for remote commands
 */
#define ORTE_GPR_DELETE_SEGMENT_CMD         (uint8_t)  1
#define ORTE_GPR_PUT_CMD                    (uint8_t)  2
#define ORTE_GPR_DELETE_ENTRIES_CMD         (uint8_t)  3
#define ORTE_GPR_INDEX_CMD                  (uint8_t)  4
#define ORTE_GPR_SUBSCRIBE_CMD              (uint8_t)  5
#define ORTE_GPR_UNSUBSCRIBE_CMD            (uint8_t)  6
#define ORTE_GPR_CANCEL_TRIGGER_CMD         (uint8_t)  7
#define ORTE_GPR_GET_CMD                    (uint8_t)  8
#define ORTE_GPR_GET_CONDITIONAL_CMD        (uint8_t)  9
#define ORTE_GPR_TEST_INTERNALS_CMD         (uint8_t) 10
#define ORTE_GPR_NOTIFY_CMD                 (uint8_t) 11
#define ORTE_GPR_DUMP_ALL_CMD               (uint8_t) 12
#define ORTE_GPR_DUMP_SEGMENTS_CMD          (uint8_t) 13
#define ORTE_GPR_DUMP_TRIGGERS_CMD          (uint8_t) 14
#define ORTE_GPR_DUMP_SUBSCRIPTIONS_CMD     (uint8_t) 15
#define ORTE_GPR_DUMP_CALLBACKS_CMD         (uint8_t) 16
#define ORTE_GPR_INCREMENT_VALUE_CMD        (uint8_t) 17
#define ORTE_GPR_DECREMENT_VALUE_CMD        (uint8_t) 18
#define ORTE_GPR_COMPOUND_CMD               (uint8_t) 19
#define ORTE_GPR_CLEANUP_JOB_CMD            (uint8_t) 20
#define ORTE_GPR_CLEANUP_PROC_CMD           (uint8_t) 21
#define ORTE_GPR_DUMP_A_TRIGGER_CMD         (uint8_t) 22
#define ORTE_GPR_DUMP_A_SUBSCRIPTION_CMD    (uint8_t) 23
#define ORTE_GPR_DUMP_SEGMENT_SIZE_CMD      (uint8_t) 24
#define ORTE_GPR_ERROR                      (uint8_t)0xff

typedef uint8_t orte_gpr_cmd_flag_t;
#define ORTE_GPR_CMD_T ORTE_UINT8

   ORTE_DECLSPEC int orte_gpr_base_open(void);
   ORTE_DECLSPEC int orte_gpr_base_select(void);
   ORTE_DECLSPEC int orte_gpr_base_close(void);

   ORTE_DECLSPEC int orte_gpr_base_create_value(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);
                               
   ORTE_DECLSPEC int orte_gpr_base_create_keyval(orte_gpr_keyval_t **keyval,
                                                 char *key,
                                                 orte_data_type_t type,
                                                 void *data);
                                                 
   ORTE_DECLSPEC int orte_gpr_base_put_1(orte_gpr_addr_mode_t addr_mode,
                               char *segment, char **tokens,
                               char *key, orte_data_value_t *value);


   ORTE_DECLSPEC int orte_gpr_base_put_N(orte_gpr_addr_mode_t addr_mode,
                               char *segment, char **tokens,
                               orte_std_cntr_t n, char **keys,
                               orte_data_value_t **data_values);

   ORTE_DECLSPEC int orte_gpr_base_subscribe_1(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);


   ORTE_DECLSPEC int orte_gpr_base_subscribe_N(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);


   ORTE_DECLSPEC int orte_gpr_base_define_trigger(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);

   ORTE_DECLSPEC int orte_gpr_base_define_trigger_level(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_std_cntr_t *levels,
                                        orte_gpr_trigger_cb_fn_t cbfunc,
                                        void *user_tag);

    /* general usage functions */
    ORTE_DECLSPEC int orte_gpr_base_pack_delete_segment(orte_buffer_t *cmd,
                                                        char *segment);
    ORTE_DECLSPEC int orte_gpr_base_unpack_delete_segment(orte_buffer_t *buffer, int *ret);

    ORTE_DECLSPEC int orte_gpr_base_pack_delete_entries(orte_buffer_t *buffer,
                    orte_gpr_addr_mode_t mode,
                    char *segment, char **tokens, char **keys);
    ORTE_DECLSPEC int orte_gpr_base_unpack_delete_entries(orte_buffer_t *buffer, int *ret);

    ORTE_DECLSPEC int orte_gpr_base_pack_index(orte_buffer_t *cmd, char *segment);
    ORTE_DECLSPEC int orte_gpr_base_unpack_index(orte_buffer_t *cmd, int *ret, orte_std_cntr_t *cnt,
                                                 char ***index);

    ORTE_DECLSPEC int orte_gpr_base_pack_subscribe(orte_buffer_t *cmd,
                    orte_std_cntr_t num_subs,
                    orte_gpr_subscription_t **subscriptions,
                    orte_std_cntr_t num_trigs, orte_gpr_trigger_t **trig);
    ORTE_DECLSPEC int orte_gpr_base_unpack_subscribe(orte_buffer_t *buffer, int *ret);

    ORTE_DECLSPEC int orte_gpr_base_pack_unsubscribe(orte_buffer_t *cmd,
                      orte_gpr_subscription_id_t id);
    ORTE_DECLSPEC int orte_gpr_base_unpack_unsubscribe(orte_buffer_t *buffer, int *ret);

    ORTE_DECLSPEC int orte_gpr_base_pack_cancel_trigger(orte_buffer_t *cmd,
                     orte_gpr_trigger_id_t id);
    ORTE_DECLSPEC int orte_gpr_base_unpack_cancel_trigger(orte_buffer_t *buffer, int *ret);

    ORTE_DECLSPEC int orte_gpr_base_pack_put(orte_buffer_t *cmd,
                                             orte_std_cntr_t cnt, orte_gpr_value_t **values);
    ORTE_DECLSPEC int orte_gpr_base_unpack_put(orte_buffer_t *buffer, int *ret);

    ORTE_DECLSPEC int orte_gpr_base_pack_get(orte_buffer_t *cmd,
                  orte_gpr_addr_mode_t mode,
                  char *segment, char **tokens, char **keys);
    ORTE_DECLSPEC int orte_gpr_base_pack_get_conditional(orte_buffer_t *cmd,
                    orte_gpr_addr_mode_t mode,
                    char *segment, char **tokens, char **keys,
                    orte_std_cntr_t num_conditions, orte_gpr_keyval_t **conditions);

    ORTE_DECLSPEC int orte_gpr_base_unpack_get(orte_buffer_t *buffer, int *ret,
                   orte_std_cntr_t *cnt, orte_gpr_value_t ***values);

    ORTE_DECLSPEC int orte_gpr_base_pack_dump_all(orte_buffer_t *cmd);
    ORTE_DECLSPEC int orte_gpr_base_pack_dump_segments(orte_buffer_t *cmd, char *segment);
    ORTE_DECLSPEC int orte_gpr_base_pack_dump_triggers(orte_buffer_t *cmd,
                   orte_gpr_trigger_id_t start);
    ORTE_DECLSPEC int orte_gpr_base_pack_dump_subscriptions(orte_buffer_t *cmd,
                   orte_gpr_subscription_id_t start);
    ORTE_DECLSPEC int orte_gpr_base_pack_dump_a_trigger(orte_buffer_t *cmd,
                        char *name, orte_gpr_trigger_id_t id);
    ORTE_DECLSPEC int orte_gpr_base_pack_dump_a_subscription(orte_buffer_t *cmd,
                        char *name,
                        orte_gpr_subscription_id_t id);