gpr.h

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

/* -*- C -*-
 *
 * Copyright (c) 2004-2005 The Trustees of Indiana University and Indiana
 *                         University Research and Technology
 *                         Corporation.  All rights reserved.
 * Copyright (c) 2004-2005 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
 * @page gpr_api
 */

/**
 *  \brief General Purpose Registry (GPR) API
 *
 * The Open MPI General Purpose Registry (GPR)
 */

#ifndef ORTE_GPR_H_
#define ORTE_GPR_H_

/*
 * includes
 */

#include "orte_config.h"

#include <sys/types.h>

#include "orte/orte_constants.h"
#include "opal/class/opal_list.h"

#include "opal/mca/mca.h"
#include "orte/mca/ns/ns_types.h"
#include "orte/mca/rml/rml_types.h"

#include "orte/dss/dss_types.h"
#include "orte/mca/gpr/gpr_types.h"
#include "orte/mca/rml/rml_types.h"


#if defined(c_plusplus) || defined(__cplusplus)
extern "C" {
#endif

/*
 * Component functions that MUST be provided
 */

/*
 * Perform any one-time initialization required by the module
 * after RML/NS are available.
 */
typedef int (*orte_gpr_base_module_init_fn_t)(void);

/*
 * Begin recording a compound command.
 * Normally, the registry executes each command as it is called. This, however, can result
 * in an undesirable amount of network traffic. To reduce the traffic, this command allows
 * the user to aggregate a set of registry commands - in any combination of put, get, index,
 * or any other command - to be executed via a single communication to the registry.
 *
 * While recording, all registry commands are stored in a buffer instead of being immediately
 * executed. Thus, commands that retrieve information (e.g., "get") will return a NULL
 * during recording. Values from these commands will be returned when the compound
 * command is actually executed.
 *
 * The process of recording a compound command is thread safe. Threads attempting to
 * record commands are held on a lock until given access in their turn.
 *
 * @param None
 * @retval ORTE_SUCCESS Compound command recorder is active.
 * @retval ORTE_ERROR Compound command recorder did not activate.
 *
 * @code
 * ompi_gpr.begin_compound_cmd();
 * @endcode
 *
 */
typedef int (*orte_gpr_base_module_begin_compound_cmd_fn_t)(void);

/*
 * Stop recording a compound command
 * Terminates the recording process and clears the buffer of any previous commands
 *
 * @param None
 * @retval ORTE_SUCCESS Recording stopped and buffer successfully cleared
 * @retval ORTE_ERROR Didn't work - no idea why it wouldn't
 *
 * @code
 * orte_gpr.stop_compound_cmd();
 * @endcode
 *
 */
typedef int (*orte_gpr_base_module_stop_compound_cmd_fn_t)(void);

/*
 * Execute the compound command (BLOCKING)
 * Execute the compound command that has been recorded. The function returns a status
 * code that indicates whether or not all the included commands were successfully
 * executed. Failure of any command contained in the compound command will terminate
 * execution of the compound command list and return an error to the caller.
 *
 * @param none
 * @retval ORTE_SUCCESS All commands in the list were successfully executed.
 * @retval ORTE_ERROR(s) A command in the list failed, returning the indicated
 * error code.
 *
 * @code
 * status_code = orte_gpr.exec_compound_cmd();
 * @endcode
 *
 */
typedef int (*orte_gpr_base_module_exec_compound_cmd_fn_t)(void);


/*
 * Cleanup a job from the registry
 * Remove all references to a given job from the registry. This includes removing
 * all segments "owned" by the job, and removing all process names from dictionaries
 * in the registry.
 *
 * @param jobid The jobid to be cleaned up.
 *
 * @retval ORTE_SUCCESS Operation was successfully completed.
 * @retval ORTE_ERROR(s) Operation failed, returning the provided error code.
 *
 * @code
 * status_code = orte_gpr.cleanup_job(jobid);
 * @endcode
 *
 */
typedef int (*orte_gpr_base_module_cleanup_job_fn_t)(orte_jobid_t jobid);

/*
 * Cleanup a process from the registry
 * Remove all references to a given process from the registry. This includes removing
 * the process name from all dictionaries in the registry, all subscriptions, etc.
 * It also includes reducing any synchros on the job segment.
 *
 * @param proc A pointer to the process name to be cleaned up.
 *
 * @retval ORTE_SUCCESS Operation was successfully completed.
 * @retval ORTE_ERROR(s) Operation failed, returning the provided error code.
 *
 * @code
 * status_code = orte_gpr.cleanup_process(&proc);
 * @endcode
 *
 */
typedef int (*orte_gpr_base_module_cleanup_proc_fn_t)(orte_process_name_t *proc);

/*
 * Define and initialize a job segment
 * The registry contains a segment for each job that stores data on each
 * process within that job. Although the registry can create this segment
 * "on-the-fly", it is more efficient to initialize the segment via a separate
 * command - thus allowing the registry to allocate the base storage for all
 * the processes in a single malloc.
 *
 * @param name A character string indicating the name of the segment.
 * @param num_slots The number of containers expected in this segment. This
 * is just the starting number requested by the user - the registry will
 * dynamically expand the segment as required.
 *
 * @retval ORTE_SUCCESS The operation was successfully executed.
 * @retval ORTE_ERROR(s) An appropriate error code is returned.
 *
 * @code
 * status_code = orte_gpr.preallocate_segment("MY_SEGMENT", num_slots);
 * @endcode
 */
typedef int (*orte_gpr_base_module_preallocate_segment_fn_t)(char *name, orte_std_cntr_t num_slots);

/*
 * Delete a segment from the registry (BLOCKING)
 * This command removes an entire segment from the registry, including all data objects,
 * associated subscriptions, and synchros. This is a non-reversible process, so it should
 * be used with care.
 *
 * @param segment Character string specifying the name of the segment to be removed.
 *
 * @retval ORTE_SUCCESS Segment successfully removed.
 * @retval ORTE_ERROR(s) Segment could not be removed for some reason - most
 * likely, the segment name provided was not found in the registry.
 *
 * @code
 * status_code = orte_gpr.delete_segment(segment);
 * @endcode
 */
typedef int (*orte_gpr_base_module_delete_segment_fn_t)(char *segment);

/*
 * Delete a segment from the registry (NON-BLOCKING)
 * A non-blocking version of delete segment.
 */
typedef int (*orte_gpr_base_module_delete_segment_nb_fn_t)(char *segment,
                                orte_gpr_notify_cb_fn_t cbfunc, void *user_tag);


/*
 * Put a data object on the registry (BLOCKING)
 * Place a data item on the registry using a blocking operation - i.e., the calling
 * program will be blocked until the operation completes.
 *
 * Each value contains the addressing mode to be used. Addresses are defined by the tokens provided
 * that describe the object being stored. The caller has the option of specifying how
 * those tokens are to be combined in describing the object. Passing a value of
 * "ORTE_REGISTRY_AND", for example, indicates that all provided tokens are to be used.
 * In contrast, a value of "ORTE_REGISTRY_OR" indicates that any of the provided tokens
 * can adequately describe the object. For the "put" command, only "ORTE_REGISTRY_XAND"
 * is accepted - in other words, the tokens must exactly match those of any existing
 * object in order for the object to be updated. In addition, the "ORTE_REGISTRY_OVERWRITE"
 * flag must be or'd into the mode to enable update of the data object. If a data object
 * is found with the identical token description, but ORTE_REGISTRY_OVERWRITE is NOT specified,
 * then an error will be generated - the data object will NOT be overwritten in this
 * situation.
 *
 * Upon completing the "put", all subscriptions registered on the
 * specified segment are checked and appropriately processed.
 *
 * @param cnt The number of value structures to be stored.
 *
 * @param **values A pointer to the start of a contiguous array of one or more
 * pointers to orte_gpr_value_t
 * objects to be stored. The registry will copy this data onto the specified segment - the
 * calling program is responsible for freeing any memory, if appropriate.
 *
 * @retval ORTE_SUCCESS The data has been stored on the specified segment, or the
 * corresponding existing data has been updated.
 *
 * @retval ORTE_ERROR(s) The data was not stored on the specified segment, or the
 * corresponding existing data was not found, or the data was found but the overwrite
 * flag was not set.
 *
 * @code
 * orte_gpr_value_t *value;
 *
 * status_code = orte_gpr.put(1, &value);
 * @endcode
 */
typedef int (*orte_gpr_base_module_put_fn_t)(orte_std_cntr_t cnt, orte_gpr_value_t **values);

/* simplified version of the put command */
typedef int (*orte_gpr_base_module_put_1_fn_t)(orte_gpr_addr_mode_t addr_mode,
                                               char *segment, char **tokens,
                                               char *key, orte_data_value_t *value);

typedef int (*orte_gpr_base_module_put_N_fn_t)(orte_gpr_addr_mode_t addr_mode,