ns.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-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:
 *
 * The Open MPI Name Server
 *
 * The Open MPI Name Server provides unique name ranges for processes
 * within the universe. Each universe will have one name server
 * running within the seed daemon.  This is done to prevent the
 * inadvertent duplication of names.
 */

#ifndef MCA_NS_H
#define MCA_NS_H

/*
 * includes
 */

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

#include "orte/dss/dss.h"

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

#include "ns_types.h"

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


/*
 * Component functions - all MUST be provided!
 */

/* Init the selected module
 */
typedef int (*orte_ns_base_module_init_fn_t)(void);

/****   CELL FUNCTIONS   ****/
/**
 * Create a new cell id.
 * Allocates a new cell id for use by the caller. The function returns an
 * existing cellid if the specified site/resource already has been assigned
 * one.
 *
 * @param site The name of the site where the cell is located.
 * @param resource The name of the resource associated with this cell (e.g., the name
 * of the cluster).
 * @param cellid The location where the cellid is to be stored.
 *
 * @retval ORTE_SUCCESS A cellid was created and returned.
 * @retval ORTE_ERROR_VALUE An error code indicative of the problem.
 *
 * @endcode
 */
typedef int (*orte_ns_base_module_create_cellid_fn_t)(orte_cellid_t *cellid,
                                char *site, char *resource);

/**
 * Get cell info
 * Retrieve the site and resource info on a cell.
 *
 * @param cellid The id of the cell who's info is being requested.
 * @param site Returns a pointer to a strdup'd string containing the site name.
 * @param resource Returns a pointer to a strdup'd string containg the resource name.
 * @retval ORTE_SUCCESS A cellid was created and returned.
 * @retval ORTE_ERROR_VALUE An error code indicative of the problem.
 */
typedef int (*orte_ns_base_module_get_cell_info_fn_t)(orte_cellid_t cellid,
                                char **site, char **resource);

/**
 * Get the cell id as a character string.
 * The get_cellid_string() function returns the cell id in a character string
 * representation. The string is created by expressing the field in hexadecimal. Memory
 * for the string is allocated by the function - releasing that allocation is the
 * responsibility of the calling program.
 *
 * @param *name A pointer to the name structure containing the name to be
 * "translated" to a string.
 *
 * @retval *name_string A pointer to the character string representation of the
 * cell id.
 * @retval NULL Indicates an error occurred - either no memory could be allocated
 * or the caller provided an incorrect name pointer (e.g., NULL).
 *
 * @code
 * cellid-string = ompi_name_server.get_cellid_string(&name)
 * @endcode
 */
typedef int (*orte_ns_base_module_get_cellid_string_fn_t)(char **cellid_string, const orte_process_name_t* name);

/**
 * Convert cellid to character string
 * Returns the cellid in a character string representation. The string is created
 * by expressing the provided cellid in hexadecimal. Memory for the string is
 * allocated by the function - releasing that allocation is the responsibility of
 * the calling program.
 *
 * @param cellid The cellid to be converted.
 *
 * @retval *cellid_string A pointer to a character string representation of the cellid.
 * @retval NULL Indicates an error occurred - probably no memory could be allocated.
 *
 * @code
 * cellid-string = ompi_name_server.convert_cellid_to_string(cellid);
 * @endcode
 */
 typedef int (*orte_ns_base_module_convert_cellid_to_string_fn_t)(char **cellid_string, const orte_cellid_t cellid);

 /**
  * Convert a string to a cellid.
  * Converts a characters string into a cellid. The character string must be a
  * hexadecimal representation of a valid cellid.
  *
  * @param cellidstring The string to be converted.
  *
  * @retval cellid The resulting cellid
  * @retval MCA_NS_BASE_CELLID_MAX String could not be converted.
  *
  * @code
  * cellid = ompi_name_server.convert_string_to_cellid(cellidstring);
  * @endcode
  */
typedef int (*orte_ns_base_module_convert_string_to_cellid_fn_t)(orte_cellid_t *cellid, const char *cellidstring);


/****    NODE FUNCTIONS    ****/
/*
 * Get an array of node id's
 * Given the cell and a NULL-terminated array of names of nodes within it, this function assigns an id to represent
 * each node within the cell.
 */
typedef int (*orte_ns_base_module_create_nodeids_fn_t)(orte_nodeid_t **nodes, orte_std_cntr_t *nnodes,
                                                       orte_cellid_t cellid, char **nodename);

/*
 * Get node info
 * Retrieve the names of an array of nodes given their cellid and nodeids. The cellid
 * is required as the nodeids are only unique within a given cell.
 *
 * @param cellid The id of the cell of the node.
 * @param nodeids The ids of the node.
 * @param nodenames Returns a pointer to a NULL-terminated array of strdup'd strings containing the node names.
 * @retval ORTE_SUCCESS The nodename was created and returned.
 * @retval ORTE_ERROR_VALUE An error code indicative of the problem.
 */
typedef int (*orte_ns_base_module_get_node_info_fn_t)(char ***nodename, orte_cellid_t cellid,
                                                      orte_std_cntr_t num_nodes, orte_nodeid_t *nodeids);

/*
 * Convert nodeid to character string
 * Returns the nodeid in a character string representation. The string is created
 * by expressing the provided nodeid in decimal. Memory for the string is
 * allocated by the function - releasing that allocation is the responsibility of
 * the calling program.
 *
 * @param nodeid The nodeid to be converted.
 *
 * @param *nodeid_string A pointer to a character string representation of the nodeid.
 * @retval ORTE_SUCCESS The string was created and returned.
 * @retval ORTE_ERROR_VALUE An error code indicative of the problem.
 */
typedef int (*orte_ns_base_module_convert_nodeid_to_string_fn_t)(char **nodeid_string, const orte_nodeid_t nodeid);

/*
 * Convert a string to a nodeid.
 * Converts a characters string into a nodeid. The character string must be a
 * decimal representation of a valid nodeid.
 *
 * @param nodeidstring The string to be converted.
 *
 * @param nodeid A pointer to a location where the resulting nodeid is to be stored.
 * @retval ORTE_SUCCESS The string was created and returned.
 * @retval ORTE_ERROR_VALUE An error code indicative of the problem.
 */
typedef int (*orte_ns_base_module_convert_string_to_nodeid_fn_t)(orte_nodeid_t *nodeid, const char *nodeidstring);


/****   JOB ID FUNCTIONS   ****/
/**
 * Create a new job id.
 * Allocate a new job id for use by the caller.
 * 
 * The 0 job id is reserved for daemons within the system and will not be allocated.
 * Developers should therefore assume that the daemon job id is automatically allocated
 * and proceed to request names against it.
 *
 * @param None
 * @param jobid A pointer to the location where the jobid is to be returned.
 * @param attrs A list of attributes that describe any conditions to be placed on
 * the assigned jobid. For example, specifying USE_PARENT indicates that the specified
 * jobid is to be identified as the parent of the new jobid. USE_ROOT indicates that
 * the root of the job family of the specified jobid is to be identified as the parent.
 */
typedef int (*orte_ns_base_module_create_jobid_fn_t)(orte_jobid_t *jobid, opal_list_t *attrs);

/*
 * Get job descendants
 * Given a jobid, return the array of jobids that descend from this one.
 */
typedef int (*orte_ns_base_module_get_job_descendants_fn_t)(orte_jobid_t** descendants,
                                                            orte_std_cntr_t *num_desc,
                                                            orte_jobid_t job);
             
/*
 * Get job children
 * Given a jobid, return the array of jobids that are direct children of that job
 */
typedef int (*orte_ns_base_module_get_job_children_fn_t)(orte_jobid_t** children,
                                                         orte_std_cntr_t *num_childs,
                                                         orte_jobid_t job);

/*
 * Get root job from job family
 * Given a jobid, return the jobid at the head of this job's family. If the jobid provided is the
 * root for that family, that value will be returned.
 */
typedef  int (*orte_ns_base_module_get_root_job_fn_t)(orte_jobid_t *root_job, orte_jobid_t job);

/*
 * Get parent jobid
 * Given a jobid, return the parent job from which it descended. If the provided jobid is the
 * root (i.e., has no parent), this function will return that same value.
 */
typedef int (*orte_ns_base_module_get_parent_job_fn_t)(orte_jobid_t *parent, orte_jobid_t job);

/**
 * Reserve a range of process id's.
 * The reserve_range() function reserves a range of vpid's for the given jobid.
 * Note that the cellid does not factor into this request - jobid's span the entire universe,
 * hence the cell where the process is currently executing is irrelevant to this request.
 *
 * @param jobid The id of the job for which the vpid's are to be reserved.
 * @param range The number of vpid's to be reserved. The function will find the
 * next available process id and assign range-number of sequential id's to the caller.
 * These id's will be reserved - i.e., they cannot be assigned to any subsequent caller.
 *
 * @retval startid The starting value of the reserved range of vpid's. A value of MCA_NS_BASE_VPID_MAX
 * indicates that an error occurred.
 *
 * @code
 * starting_procid = ompi_name_server.reserve_range(jobid, range)
 * @endcode
 */
typedef int (*orte_ns_base_module_reserve_range_fn_t)(orte_jobid_t job,
                                                      orte_vpid_t range,
                                                      orte_vpid_t *startvpid);

/**
 * Get the job id as a character string.
 * The get_jobid_string() function returns the job id in a character string
 * representation. The string is created by expressing the field in hexadecimal. Memory
 * for the string is allocated by the function - releasing that allocation is the
 * responsibility of the calling program.
 *
 * @param *name A pointer to the name structure containing the name to be
 * "translated" to a string.
 *
 * @retval *name_string A pointer to the character string representation of the
 * job id.
 * @retval NULL Indicates an error occurred - either no memory could be allocated
 * or the caller provided an incorrect name pointer (e.g., NULL).
 *
 * @code
 * jobid-string = ompi_name_server.get_jobid_string(&name)
 * @endcode
 */
typedef int (*orte_ns_base_module_get_jobid_string_fn_t)(char **jobid_string, const orte_process_name_t* name);

/**
 * Convert jobid to character string
 * The convert_jobid_to_string() function returns the jobid in a character string representation.
 * The string is created by expressing the provided jobid in hexadecimal. Memory
 * for the string is allocated by the function - releasing that allocation is the
 * responsibility of the calling program.
 *
 * @param jobid The jobid to be converted.
 *
 * @retval *jobid_string A pointer to a character string representation of the
 * jobid.
 * @retval NULL Indicates an error occurred - probably no memory could be allocated.
 *
 * @code
 * jobid-string = ompi_name_server.convert_jobid_to_string(jobid);
 * @endcode
 */
typedef int (*orte_ns_base_module_convert_jobid_to_string_fn_t)(char **jobid_string, const orte_jobid_t jobid);

/**
 * Convert a string to a jobid
 * Converts a character string into a jobid. The character string must be a hexadecimal
 * representation of a valid jobid.
 *
 * @param jobidstring The string to be converted.
 *
 * @retval jobid The resulting jobid.
 * @retval MCA_NS_BASE_JOBID_MAX String could not be converted.
 *
 * @code
 * jobid = ompi_name_server.convert_string_to_jobid(jobidstring);
 * @endcode
 *
 */
typedef int (*orte_ns_base_module_convert_string_to_jobid_fn_t)(orte_jobid_t *jobid, const char* jobidstring);



/**** NAME FUNCTIONS ****/
/**
 * Obtain a single new process name.
 * The create_process_name() function creates a single process name structure and fills the
 * fields with the provided values.
 *
 * @param cell The cell for which the process name is intended. Usually, this is