OpenMPI  0.1.1
proc.h File Reference

Process identification structure interface. More...

#include "ompi_config.h"
#include "ompi/constants.h"
#include "ompi/types.h"
#include "opal/class/opal_list.h"
#include "opal/dss/dss_types.h"
#include "opal/mca/paffinity/paffinity.h"
#include "orte/types.h"

Go to the source code of this file.

Data Structures

struct  ompi_proc_t
 Remote Open MPI process structure. More...
 

Typedefs

typedef struct ompi_proc_t ompi_proc_t
 

Functions

 OBJ_CLASS_DECLARATION (ompi_proc_t)
 
OMPI_DECLSPEC int ompi_proc_init (void)
 Initialize the OMPI process subsystem. More...
 
OMPI_DECLSPEC int ompi_proc_complete_init (void)
 Complete filling up the proc information (arch, name and locality) for all procs related to this job. More...
 
OMPI_DECLSPEC int ompi_proc_finalize (void)
 Finalize the OMPI Process subsystem. More...
 
OMPI_DECLSPEC ompi_proc_t ** ompi_proc_world (size_t *size)
 Returns the list of proc instances associated with this job. More...
 
OMPI_DECLSPEC ompi_proc_t ** ompi_proc_all (size_t *size)
 Returns the list of all known proc instances. More...
 
OMPI_DECLSPEC ompi_proc_t ** ompi_proc_self (size_t *size)
 Returns a list of the local process. More...
 
static ompi_proc_tompi_proc_local (void)
 Returns a pointer to the local process. More...
 
OMPI_DECLSPEC ompi_proc_tompi_proc_find (const orte_process_name_t *name)
 Returns the proc instance for a given name. More...
 
OMPI_DECLSPEC int ompi_proc_pack (ompi_proc_t **proclist, int proclistsize, opal_buffer_t *buf)
 Pack proc list into portable buffer. More...
 
OMPI_DECLSPEC int ompi_proc_unpack (opal_buffer_t *buf, int proclistsize, ompi_proc_t ***proclist, int *newproclistsize, ompi_proc_t ***newproclist)
 Unpack a portable buffer of procs. More...
 
OMPI_DECLSPEC int ompi_proc_refresh (void)
 Refresh the OMPI process subsystem. More...
 

Variables

OMPI_DECLSPEC ompi_proc_tompi_proc_local_proc
 Pointer to the ompi_proc_t structure for the local process. More...
 

Detailed Description

Process identification structure interface.

Process identification structure interface. The ompi_proc_t structure contatins basic information about the remote (and local) processes.

Function Documentation

OMPI_DECLSPEC ompi_proc_t** ompi_proc_all ( size_t *  size)

Returns the list of all known proc instances.

Returns the list of all known proc instances, including those in other MPI_COMM_WORLDs. It is possible that we may no longer be connected to some of the procs returned (in the MPI sense of the word connected). In a strictly MPI-1 application, this function will return the same information as ompi_proc_world().

Note
The reference count of each process in the array is incremented and the caller is responsible for releasing each process in the array, as well as freeing the array.
Parameters
[in]sizeNumber of processes in the ompi_proc_t array
Returns
Array of pointers to proc instances in the current known universe, or NULL if there is an internal failure.

References OBJ_RETAIN, opal_list_get_end(), opal_list_get_first(), opal_list_get_next, opal_list_get_size(), OPAL_THREAD_LOCK, and OPAL_THREAD_UNLOCK.

OMPI_DECLSPEC int ompi_proc_complete_init ( void  )

Complete filling up the proc information (arch, name and locality) for all procs related to this job.

This function is to be called only after the modex exchange has been completed.

Return values
OMPI_SUCCESSAll information correctly set.
OMPI_ERRORSome info could not be initialized.

Complete filling up the proc information (arch, name and locality) for all procs related to this job.

The second step is the important one, it sets the properties of the remote process, such as architecture, node name and locality flags.

This function is to be called only after the modex exchange has been performed, in order to allow the modex to carry the data instead of requiring the runtime to provide it.

References orte_proc_info_t::nodename, OBJ_RELEASE, ompi_modex_recv_key_value(), opal_list_get_end(), opal_list_get_first(), opal_list_get_next, OPAL_THREAD_LOCK, OPAL_THREAD_UNLOCK, OPAL_UINT32, ORTE_PROC_MY_NAME, orte_process_info, orte_show_help(), ompi_proc_t::proc_arch, ompi_proc_t::proc_convertor, ompi_proc_t::proc_flags, ompi_proc_t::proc_hostname, ompi_proc_t::proc_name, and orte_process_name_t::vpid.

Referenced by ompi_mpi_init().

OMPI_DECLSPEC int ompi_proc_finalize ( void  )

Finalize the OMPI Process subsystem.

Finalize the Open MPI process subsystem. This function will release all memory created during the life of the application, including all ompi_proc_t structures.

Return values
OMPI_SUCCESSSystem successfully finalized

References OBJ_DESTRUCT, OBJ_RELEASE, opal_list_get_end(), and opal_list_get_first().

Referenced by ompi_mpi_finalize().

OMPI_DECLSPEC ompi_proc_t* ompi_proc_find ( const orte_process_name_t name)

Returns the proc instance for a given name.

Returns the proc instance for the specified process name. The reference count for the proc instance is not incremented by this function.

Parameters
[in]nameThe process name to look for
Returns
Pointer to the process instance for name

References opal_list_get_end(), opal_list_get_first(), opal_list_get_next, OPAL_THREAD_LOCK, OPAL_THREAD_UNLOCK, orte_ns_cmp_bitmask_t, and ompi_proc_t::proc_name.

Referenced by mca_pml_bfo_recv_frag_callback_rndvrestartnotify().

OMPI_DECLSPEC int ompi_proc_init ( void  )

Initialize the OMPI process subsystem.

Initialize the Open MPI process subsystem. This function will query the run-time environment and build a list of the proc instances in the current MPI_COMM_WORLD. The local information not easily determined by the run-time ahead of time (architecture and hostname) will be published during this call.

Note
While an ompi_proc_t will exist with mostly valid information for each process in the MPI_COMM_WORLD at the conclusion of this call, some information will not be immediately available. This includes the architecture and hostname, which will be available by the conclusion of the stage gate.
Return values
OMPI_SUCESSSystem successfully initialized
OMPI_ERRORInitialization failed due to unspecified error

References orte_process_name_t::jobid, orte_proc_info_t::nodename, orte_proc_info_t::num_procs, OBJ_CONSTRUCT, ompi_modex_send_key_value(), opal_list_append, OPAL_UINT32, ORTE_PROC_MY_NAME, orte_process_info, ompi_proc_t::proc_arch, ompi_proc_t::proc_flags, ompi_proc_t::proc_hostname, ompi_proc_t::proc_name, and orte_process_name_t::vpid.

Referenced by ompi_mpi_init().

static ompi_proc_t* ompi_proc_local ( void  )
inlinestatic

Returns a pointer to the local process.

Returns a pointer to the local process. Unlike ompi_proc_self(), the reference count on the local proc instance is not modified by this function.

Returns
Pointer to the local process structure

References ompi_proc_local_proc.

Referenced by mca_btl_gm_add_procs(), mca_btl_sctp_add_procs(), mca_btl_sm_add_procs(), mca_btl_smcuda_add_procs(), mca_btl_tcp_add_procs(), mca_btl_template_add_procs(), mca_btl_udapl_add_procs(), and ompi_osc_base_process_op().

OMPI_DECLSPEC int ompi_proc_pack ( ompi_proc_t **  proclist,
int  proclistsize,
opal_buffer_t buf 
)

Pack proc list into portable buffer.

This function takes a list of ompi_proc_t pointers (e.g. as given in groups) and returns a orte buffer containing all information needed to add the proc to a remote list. This includes the ORTE process name, the architecture, and the hostname. Ordering is maintained. The buffer is packed to be sent to a remote node with different architecture (endian or word size). The buffer can be dss unloaded to be sent using MPI or send using rml_send_packed().

Parameters
[in]proclistList of process pointers
[in]proclistsizeLength of the proclist array
[in,out]bufAn orte_buffer containing the packed names. The buffer must be constructed but empty when passed to this function
Return values
OMPI_SUCCESSSuccess
OMPI_ERRORUnspecified error

References OPAL_STRING, OPAL_THREAD_LOCK, OPAL_THREAD_UNLOCK, OPAL_UINT32, and ORTE_NAME.

OMPI_DECLSPEC int ompi_proc_refresh ( void  )

Refresh the OMPI process subsystem.

Refresh the Open MPI process subsystem. This function will update the list of proc instances in the current MPI_COMM_WORLD with data from the run-time environemnt.

Note
This is primarily used when restarting a process and thus need to update the jobid and node name.
Return values
OMPI_SUCESSSystem successfully refreshed
OMPI_ERRORRefresh failed due to unspecified error

References orte_process_name_t::jobid, orte_proc_info_t::nodename, OBJ_RELEASE, opal_list_get_end(), opal_list_get_first(), opal_list_get_next, OPAL_THREAD_LOCK, OPAL_THREAD_UNLOCK, ORTE_PROC_MY_NAME, orte_process_info, orte_show_help(), ompi_proc_t::proc_arch, ompi_proc_t::proc_convertor, ompi_proc_t::proc_flags, ompi_proc_t::proc_hostname, and ompi_proc_t::proc_name.

OMPI_DECLSPEC ompi_proc_t** ompi_proc_self ( size_t *  size)

Returns a list of the local process.

Returns a list containing the local process (and only the local process). Has calling semantics similar to ompi_proc_world() and ompi_proc_all().

Note
The reference count of each process in the array is incremented and the caller is responsible for releasing each process in the array, as well as freeing the array.
Parameters
[in]sizeNumber of processes in the ompi_proc_t array
Returns
Array of pointers to proc instances in the current known universe, or NULL if there is an internal failure.

References OBJ_RETAIN, and ompi_proc_local_proc.

OMPI_DECLSPEC int ompi_proc_unpack ( opal_buffer_t buf,
int  proclistsize,
ompi_proc_t ***  proclist,
int *  newproclistsize,
ompi_proc_t ***  newproclist 
)

Unpack a portable buffer of procs.

This function unpacks a packed list of ompi_proc_t structures and returns the ordered list of proc structures. If the given proc is already "known", the architecture and hostname information in the buffer is ignored. If the proc is "new" to this process, it will be added to the global list of known procs, with information provided in the buffer. The lookup actions are always entirely local. The proclist returned is a list of pointers to all procs in the buffer, whether they were previously known or are new to this process.

Note
In previous versions of this function, The PML's add_procs() function was called for any new processes discovered as a result of this operation. That is no longer the case – the caller must use the newproclist information to call add_procs() if necessary.
The reference count for procs created as a result of this operation will be set to 1. Existing procs will not have their reference count changed. The reference count of a proc at the return of this function is the same regardless of whether NULL is provided for newproclist. The user is responsible for freeing the newproclist array.
Parameters
[in]buforte_buffer containing the packed names
[in]proclistsizenumber of expected proc-pointres
[out]proclistlist of process pointers
[out]newproclistsizeNumber of new procs added as a result of the unpack operation. NULL may be provided if information is not needed.
[out]newproclistList of new procs added as a result of the unpack operation. NULL may be provided if informationis not needed.

Return value: OMPI_SUCCESS on success OMPI_ERROR else

References orte_proc_info_t::nodename, OBJ_RELEASE, OPAL_STRING, OPAL_UINT32, ORTE_NAME, orte_process_info, orte_show_help(), ompi_proc_t::proc_arch, ompi_proc_t::proc_convertor, ompi_proc_t::proc_flags, and ompi_proc_t::proc_hostname.

OMPI_DECLSPEC ompi_proc_t** ompi_proc_world ( size_t *  size)

Returns the list of proc instances associated with this job.

Returns the list of proc instances associated with this job. Given the current association between a job and an MPI_COMM_WORLD, this function provides the process instances for the current MPI_COMM_WORLD.

Note
The reference count of each process in the array is NOT incremented - the caller is responsible for ensuring the correctness of the reference count once they are done with the array.
Parameters
[in]sizeNumber of processes in the ompi_proc_t array
Returns
Array of pointers to proc instances in the current MPI_COMM_WORLD, or NULL if there is an internal failure.

References opal_list_get_end(), opal_list_get_first(), opal_list_get_next, OPAL_THREAD_LOCK, OPAL_THREAD_UNLOCK, orte_ns_cmp_bitmask_t, and ompi_proc_t::proc_name.

Referenced by ompi_mpi_init().

Variable Documentation

OMPI_DECLSPEC ompi_proc_t* ompi_proc_local_proc

Pointer to the ompi_proc_t structure for the local process.

Pointer to the ompi_proc_t structure for the local process.

Note
This pointer is declared here to allow inline functions within this header file to access the local process quickly. Please use ompi_proc_local() instead.

Referenced by mca_btl_mx_add_procs(), mca_btl_self_add_procs(), mca_pml_bfo_recv_req_start(), mca_pml_ob1_recv_req_start(), ompi_proc_local(), and ompi_proc_self().