ns.h

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

 * the id of the cell where the process is initially planning to be spawned.
 * @param job The id of the job to which the process will belong. Process id's are
 * tracked according to jobid, but not cellid. Thus, two processes
 * can have the same process id if and only if they have different jobid's. However,
 * two processes in the same jobid cannot have the same process id, regardless
 * of whether or not they are in the same cell.
 * @param vpid The virtual process id for the name. Note that no check is made for uniqueness -
 * the caller is responsible for ensuring that the requested name is, in fact, unique
 * by first requesting reservation of an appropriate range of virtual process id's.
 *
 * @retval *name Pointer to an ompi_process_name_t structure containing the name.
 * @retval NULL Indicates an error, probably due to inability to allocate memory for
 * the name structure.
 *
 * @code
 * new_name = ompi_name_server.create_process_name(cell, job, vpid);
 * @endcode
 */
typedef int (*orte_ns_base_module_create_proc_name_fn_t)(orte_process_name_t **name,
                                                         orte_cellid_t cell,
                                                         orte_jobid_t job,
                                                         orte_vpid_t vpid);

/*
 * Create my name
 * If a process is a singleton, then it needs to create a name for itself. When
 * a persistent daemon is present, this requires a communication to that daemon.
 * Since the RML uses process names as its index into the RML communicator table,
 * the RML automatically assigns a name to each process when it first attempts
 * to communicate. This function takes advantage of that behavior to ensure that
 * one, and ONLY one, name gets assigned to the process
 */
typedef int (*orte_ns_base_module_create_my_name_fn_t)(void);

/**
 * Convert a string representation to a process name.
 * The convert_string_to_process_name() function converts a string representation of a process
 * name into an Open MPI name structure. The string must be of the proper form - i.e., it
 * must be in the form "cellid.jobid.vpid", where each field is expressed in hexadecimal form.
 *
 * @param *name_string A character string representation of a process name.
 *
 * @retval *name Pointer to an ompi_process_name_t structure containing the name.
 * @retval NULL Indicates an error, probably due to inability to allocate memory for
 * the name structure.
 *
 * @code
 * name = ompi_name_server.convert_string_to_process_name(name_string);
 * @endcode
 */
typedef int (*orte_ns_base_module_convert_string_to_process_name_fn_t)(orte_process_name_t **name,
                                                                       const char* name_string);


/**
 * Get the process name as a character string.
 * The get_proc_name_string() function returns the entire process name in a
 * character string representation. The string is created by expressing each
 * field in hexadecimal separated by periods, as follows:
 *
 * sprintf(string_name, "%x.%x.%x", cellid, jobid, vpid)
 *
 * The memory required 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
 * full name.
 * @retval NULL Indicates an error occurred - either no memory could be allocated
 * or the caller provided an incorrect name pointer (e.g., NULL).
 *
 * @code
 * name-string = ompi_name_server.get_proc_name_string(&name)
 * @endcode
 */
typedef int (*orte_ns_base_module_get_proc_name_string_fn_t)(char **name_string,
                                                             const orte_process_name_t* name);

/**
 * Compare two name values.
 * The compare() function checks the value of the fields in the two
 * provided names, and returns a value indicating if the first one is less than, greater
 * than, or equal to the second. The value of each field is compared in a hierarchical
 * fashion, with cellid first, followed by jobid and vpid in sequence. The bit-mask
 * indicates which fields are to be included in the comparison. Fields not included via the
 * bit-mask are ignored. Thus, the caller may request that any combination of the three fields
 * be included in the comparison.
 *
 * @param fields A bit-mask indicating which fields are to be included in the comparison. The
 * comparison is performed on a hierarchical basis, with cellid being first, followed by
 * jobid and then vpid. Each field can be included separately, thus allowing the caller
 * to configure the comparison to meet their needs.
 * @param *name1 A pointer to the first name structure.
 * @param *name2 A pointer to the second name structure.
 *
 * @retval -1 The indicated fields of the first provided name are less than the same
 * fields of the second provided name.
 * @retval 0 The indicated fields of the two provided names are equal.
 * @retval +1 The indicated fields of the first provided name is greater than the same
 * fields of the second provided name.
 *
 * The function returns a large negative value if there is an error.
 *
 * @code
 * result = ompi_name_server.compare(bit_mask, &name1, &name2)
 * @endcode
 */
typedef int (*orte_ns_base_module_compare_fields_fn_t)(orte_ns_cmp_bitmask_t fields,
                                                       const orte_process_name_t* name1,
                                                       const orte_process_name_t* name2);


/****   VPID FUNCTIONS   ****/
/**
 * Get the virtual process id as a character string.
 * The get_vpid_string() function returns the vpid 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
 * vpid.
 * @retval NULL Indicates an error occurred - either no memory could be allocated
 * or the caller provided an incorrect name pointer (e.g., NULL).
 *
 * @code
 * vpid-string = ompi_name_server.get_vpid_string(&name)
 * @endcode
 */
typedef int (*orte_ns_base_module_get_vpid_string_fn_t)(char **vpid_string, const orte_process_name_t* name);

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

 /**
  * Convert a string to a vpid.
  * Converts a characters string into a vpid. The character string must be a
  * hexadecimal representation of a valid vpid.
  *
  * @param vpidstring The string to be converted.
  *
  * @retval vpid The resulting vpid
  * @retval MCA_NS_BASE_VPID_MAX String could not be converted.
  *
  * @code
  * vpid = ompi_name_server.convert_string_to_vpid(vpidstring);
  * @endcode
  */
typedef int (*orte_ns_base_module_convert_string_to_vpid_fn_t)(orte_vpid_t *vpid, const char* vpidstring);



/**** TAG SERVER ****/
/*
 * Allocate a tag
 * If name is NULL, tag server provides next unique tag but cannot look
 * that number up again for anyone else.
 */
typedef int (*orte_ns_base_module_assign_rml_tag_fn_t)(orte_rml_tag_t *tag,
                                                   char *name);

/**** DATA TYPE SERVER ****/
/* This function defines a new data type and gives it a system-wide unique
 * identifier for use in the data packing subsystem. Only called from the
 * dps when needing a new identifier.
 */
typedef int (*orte_ns_base_module_define_data_type_fn_t)(
                     const char *name,
                     orte_data_type_t *type);


/****    PEER RETRIEVAL    ****/
/**
 * Get the process names of all processes in the specified conditions. It is
 * sometimes necessary for a process to communicate to all processes of a
 * given job, all processes in a given cell or on a given node, etc. The RML
 * communication system utilizes the process name as its "pointer" for
 * sending messages to another process. This function returns an array of
 * process name pointers that contains the names of all processes that
 * meet the specified combination of attributes.
 *
 * @param procs The location where the address of the array of pointers
 * is to be stored. The function will dynamically allocate space for the
 * array - the caller is responsible for releasing this space.
 * @param num_procs The location where the number of entries in the
 * returned array is to be stored.
 * @param attributes A list of conditions to be used in defining the
 * peers to be included in the returned array. This can include a
 * request that all peers for the parent job be returned, for example.
 * More common options would be to specify a cell or job.
 *
 * NOTE The combination of ORTE_CELLID_WILDCARD and ORTE_JOBID_WILDCARD
 * in the attribute list will cause the function to return the names of *all*
 * processes currently active in the universe.
 *
 */
typedef int (*orte_ns_base_module_get_peers_fn_t)(orte_process_name_t **procs,
                                                  orte_std_cntr_t *num_procs,
                                                  opal_list_t *attributes);


/*
 * DIAGNOSTIC INTERFACES
 */
typedef int (*orte_ns_base_module_dump_cells_fn_t)(void);

typedef int (*orte_ns_base_module_dump_jobs_fn_t)(void);

typedef int (*orte_ns_base_module_dump_tags_fn_t)(void);

typedef int (*orte_ns_base_module_dump_datatypes_fn_t)(void);


/*
 * Ver 2.0
 */
struct mca_ns_base_module_2_0_0_t {
    /* init */
    orte_ns_base_module_init_fn_t                           init;
    /* cell functions */
    orte_ns_base_module_create_cellid_fn_t                  create_cellid;
    orte_ns_base_module_get_cell_info_fn_t                  get_cell_info;
    orte_ns_base_module_get_cellid_string_fn_t              get_cellid_string;
    orte_ns_base_module_convert_cellid_to_string_fn_t       convert_cellid_to_string;
    orte_ns_base_module_convert_string_to_cellid_fn_t       convert_string_to_cellid;
    /** node functions */
    orte_ns_base_module_create_nodeids_fn_t                 create_nodeids;
    orte_ns_base_module_get_node_info_fn_t                  get_node_info;
    orte_ns_base_module_convert_nodeid_to_string_fn_t       convert_nodeid_to_string;
    orte_ns_base_module_convert_string_to_nodeid_fn_t       convert_string_to_nodeid;
    /* jobid functions */
    orte_ns_base_module_create_jobid_fn_t                   create_jobid;
    orte_ns_base_module_get_job_descendants_fn_t            get_job_descendants;
    orte_ns_base_module_get_job_children_fn_t               get_job_children;
    orte_ns_base_module_get_root_job_fn_t                   get_root_job;
    orte_ns_base_module_get_parent_job_fn_t                 get_parent_job;
    orte_ns_base_module_get_jobid_string_fn_t               get_jobid_string;
    orte_ns_base_module_convert_jobid_to_string_fn_t        convert_jobid_to_string;
    orte_ns_base_module_convert_string_to_jobid_fn_t        convert_string_to_jobid;
    orte_ns_base_module_reserve_range_fn_t                  reserve_range;
    /* vpid functions */
    orte_ns_base_module_get_vpid_string_fn_t                get_vpid_string;
    orte_ns_base_module_convert_vpid_to_string_fn_t         convert_vpid_to_string;
    orte_ns_base_module_convert_string_to_vpid_fn_t         convert_string_to_vpid;
    /* name functions */
    orte_ns_base_module_create_proc_name_fn_t               create_process_name;
    orte_ns_base_module_create_my_name_fn_t                 create_my_name;
    orte_ns_base_module_convert_string_to_process_name_fn_t convert_string_to_process_name;
    orte_ns_base_module_get_proc_name_string_fn_t           get_proc_name_string;
    orte_ns_base_module_compare_fields_fn_t                 compare_fields;
    /* peer functions */
    orte_ns_base_module_get_peers_fn_t                      get_peers;
    /* tag server functions */
    orte_ns_base_module_assign_rml_tag_fn_t                 assign_rml_tag;
    /* data type functions */
    orte_ns_base_module_define_data_type_fn_t               define_data_type;
    /* diagnostic functions */
    orte_ns_base_module_dump_cells_fn_t                     dump_cells;
    orte_ns_base_module_dump_jobs_fn_t                      dump_jobs;
    orte_ns_base_module_dump_tags_fn_t                      dump_tags;
    orte_ns_base_module_dump_datatypes_fn_t                 dump_datatypes;
};

typedef struct mca_ns_base_module_2_0_0_t mca_ns_base_module_2_0_0_t;
typedef mca_ns_base_module_2_0_0_t mca_ns_base_module_t;

/*
 * NS Component
 */
/**
 * Initialize the selected component.
 */
typedef mca_ns_base_module_t* (*mca_ns_base_component_init_fn_t)(int *priority);

/**
 * Finalize the selected module
 */
typedef int (*mca_ns_base_component_finalize_fn_t)(void);


/*
 * the standard component data structure
 */

struct mca_ns_base_component_2_0_0_t {
    mca_base_component_t ns_version;
    mca_base_component_data_1_0_0_t ns_data;

    mca_ns_base_component_init_fn_t ns_init;
    mca_ns_base_component_finalize_fn_t ns_finalize;
};
typedef struct mca_ns_base_component_2_0_0_t mca_ns_base_component_2_0_0_t;
typedef mca_ns_base_component_2_0_0_t mca_ns_base_component_t;



/*
 * Macro for use in components that are of type ns v2.0.0
 */
#define MCA_NS_BASE_VERSION_2_0_0 \
  /* ns v2.0 is chained to MCA v1.0 */ \
  MCA_BASE_VERSION_1_0_0, \
  /* ns v2.0 */ \
  "ns", 2, 0, 0

/* Global structure for accessing name server functions
 */
ORTE_DECLSPEC extern mca_ns_base_module_t orte_ns;  /* holds selected module's function pointers */

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

#endif