Handle Debugging:Communicator queries

Communicator queries

Important substitutions

• mqs_process -> mpid_process_handle_t
• mpid_address_t -> mpid_address_t

typedef struct _mpid_process_handle_t mpid_process_handle_t

Interface

Query a specific MPI_Comm handle and, if found and valid, return a handle that can subsequently be queried for a variety of information about this communicator. Note that the returned handle is only valid at a specific point in time. If the MPI process advances after the handle is returned, the handle should be considered stale and should therefore be freed. This function should be invoked again to obtain a new handle.

int mpid_comm_query(mpid_process_handle_t *process,
                    langHandle comm,  // The MPI handle (see mpid_type_query)
                    int language, // MPID_TYPE_LANG_C or MPID_TYPE_LANG_FORTRAN 
                    mpid_comm_handle_t **handle);

Function to query a Comm debugging handle by name (e.g. MPI_COMM_WORLD):

int mpid_comm_query_by_name(mpid_process_handle_t *process,
                            const char* name,
                            mpid_comm_handle_t **handle);

Free a handle returned by the mpid_comm_query() function or any other query function.

int mpid_comm_handle_free(mpid_comm_handle_t *handle);

Query a handle returned by mpid_comm_query() and, if found and valid, return basic information about the original communicator. All arrays returned in OUT variables are allocated by this function, but are the responsibility of the caller to be freed.

mpid_keyvalue_pair_t {
    /* String key name */
    char *key_name;
    /* String value */
    char *value;
};
int mpid_comm_query_basic(
    mpid_comm_handle_t *handle,
    char **comm_name,
    enum mpid_comm_info_bitmap_t *comm_bitflags,
    int *comm_rank,
    int *comm_size,
    int *comm_fortran_handle,
    mpid_address_t *comm_cxx_handle,
    mpid_keyvalue_pair_t **comm_extra_info);

With:

enum mpid_comm_info_bitmap_t {
    /* Predefined communicator if set (user-defined if not set) */
    MPID_COMM_INFO_PREDEFINED =      0x001,
    /* Whether this communicator is a cartesian communicator or not
       (mutually exclusive with _GRAPH and _INTERCOMM) */
    MPID_COMM_INFO_CARTESIAN =       0x002,
    /* Whether this communicator is a graph communicator or not
       (mutually exclusive with _CARTESIAN and _INTERCOMM) */
    MPID_COMM_INFO_GRAPH =           0x004,
    /* If a cartesian or graph communicator, whether the processes in
       this communicator were re-ordered when the topology was
       assigned. */
    MPID_COMM_INFO_TOPO_REORDERED =  0x008,

    /* Whether this is an intercommunicator or not (this communicator
       is an intracommunicator if this flag is not yet). */
    MPID_COMM_INFO_INTERCOMM =       0x010,

    /* This communicator has been marked for freeing by the user
       application if set */
    MPID_COMM_INFO_FREED_HANDLE =    0x020,
    /* This communicator has actually been freed by the MPI
       implementation if set */
    MPID_COMM_INFO_FREED_OBJECT =    0x040,
    /* The queried communicator is MPI_COMM_NULL */
    MPID_COMM_INFO_COMM_NULL =       0x080,

    /* The queried communicator is a C handle */
    MPID_COMM_INFO_HANDLE_C =        0x100,
    /* The queried communicator is a C++ handle */
    MPID_COMM_INFO_HANDLE_CXX =      0x200,
    /* The queried communicator is a F77/F90 integer handle */
    MPID_COMM_INFO_HANDLE_FINT =     0x400,

    /* The queried communicator has a distributed graph topology attached to it */
    MPID_COMM_INFO_DIST_GRAPH =      0x00000400,
    /* Sentinel max value */
    MPID_COMM_INFO_MAX
};

Query a handle returned by mpid_comm_query() and, if found and valid, return information about the MPI processes in this communicator. All arrays returned in OUT variables are allocated by this function, but are the responsibility of the caller to be freed.

int mpid_comm_query_procs(mpid_comm_handle_t *handle,
                          int *comm_num_local_procs,
                          mpid_process_handle_t **comm_local_procs,
                          int *comm_num_remote_procs,
                          mpid_process_handle_t **comm_remote_procs);

Query a handle returned by mpid_comm_query() and, if found and valid, return information about the topology associated with the communicator (if any). It is not an error to call this function with communicators that do not have associated topologies; such communicators will still return MPID_SUCCESS but simply return a value of 0 in the comm_out_length OUT parameter.

int mpid_comm_query_topo(mpid_comm_handle_t *handle,
                         int *comm_out_length,
                         int **comm_cart_dims_or_graph_indexes,
                         int **comm_cart_periods_or_graph_edges);

Query a handle returned by mpid_comm_query() and, if found and valid, return information about the attributes associated with the communicator (if any). It is not an error to call this function with communicators that do not have associated attributes; such communicators will still return mpid_SUCCESS but simply return a value of 0 in the comm_attrs_length OUT parameter.

int mpid_comm_query_attrs(mpid_comm_handle_t *comm_handle,
                          int *comm_num_attrs,
                          mpid_attribute_pair_t *comm_attrs);

Query a handle returned by mpid_comm_query() and, if found and valid, return an array of pending requests on this communicator. All arrays returned in OUT variables are allocated by this function, but are the responsibility of the caller to be freed.

int mpid_comm_query_requests(mpid_comm_handle_t *handle,
                             int *comm_num_requests,
                             mpid_address_t **comm_pending_requests);

alternative:

int mpid_comm_query_requests(mpid_comm_handle_t *handle,
                             int *comm_num_requests,
                             mpid_request_handle_t **comm_pending_requests);

Query a handle returned by mpid_comm_query() and, if found and valid, return arrays of MPI_File and MPI_Win handles that were derived from this communicator.

int mpid_comm_query_derived(mpid_comm_handle_t *handle,
                            int *comm_num_derived_files,
                            mpid_address_t **comm_derived_files,
                            int *comm_num_derived_windows,
                            mpid_address_t **comm_derived_windows);

Query a handle returned by mpid_comm_query() and, if found and valid, return the session this communicator was derived from

int mpid_comm_query_session(mpid_comm_handle_t *handle,
                            mpid_session_handle_t **comm_session);