OpenMPI  0.1.1
mca.h File Reference

Top-level interface for all MCA components. More...

#include "opal_config.h"

Go to the source code of this file.

Data Structures

struct  mca_base_module_2_0_0_t
 Common type for all MCA modules. More...
 
struct  mca_base_component_2_0_0_t
 Common type for all MCA components. More...
 
struct  mca_base_component_data_2_0_0_t
 Meta data for MCA v2.0.0 components. More...
 

Macros

#define MCA_BASE_MAX_TYPE_NAME_LEN   31
 Maximum length of MCA framework string names.
 
#define MCA_BASE_MAX_COMPONENT_NAME_LEN   63
 Maximum length of MCA component string names.
 
#define MCA_BASE_METADATA_PARAM_NONE   (uint32_t)0x00
 No Metadata flags.
 
#define MCA_BASE_METADATA_PARAM_CHECKPOINT   (uint32_t)0x02
 Checkpoint enabled Component.
 
#define MCA_BASE_METADATA_PARAM_DEBUG   (uint32_t)0x04
 Debug enabled/only Component.
 
#define MCA_BASE_VERSION_MAJOR   2
 Macro for framework author convenience. More...
 
#define MCA_BASE_VERSION_MINOR   0
 
#define MCA_BASE_VERSION_RELEASE   0
 
#define MCA_BASE_VERSION_2_0_0   MCA_BASE_VERSION_MAJOR, MCA_BASE_VERSION_MINOR, MCA_BASE_VERSION_RELEASE
 

Typedefs

typedef struct
mca_base_module_2_0_0_t 
mca_base_module_t
 Unversioned convenience typedef; use this name in frameworks/components to stay forward source-compatible.
 
typedef struct
mca_base_module_2_0_0_t 
mca_base_module_2_0_0_t
 Versioned convenience typedef.
 
typedef int(* mca_base_open_component_1_0_0_fn_t )(void)
 MCA component open function. More...
 
typedef int(* mca_base_close_component_1_0_0_fn_t )(void)
 MCA component close function. More...
 
typedef int(* mca_base_query_component_2_0_0_fn_t )(mca_base_module_2_0_0_t **module, int *priority)
 MCA component query function. More...
 
typedef int(* mca_base_register_component_params_2_0_0_fn_t )(void)
 MCA component parameter registration function. More...
 
typedef struct
mca_base_component_2_0_0_t 
mca_base_component_t
 Unversioned convenience typedef; use this name in frameworks/components to stay forward source-compatible.
 
typedef struct
mca_base_component_2_0_0_t 
mca_base_component_2_0_0_t
 Versioned convenience typedef.
 
typedef struct
mca_base_component_data_2_0_0_t 
mca_base_component_data_t
 Unversioned convenience typedef; use this name in frameworks/components to stay forward source-compatible.
 
typedef struct
mca_base_component_data_2_0_0_t 
mca_base_component_data_2_0_0_t
 Versioned convenience typedef.
 

Enumerations

enum  {
  MCA_SUCCESS = 0, MCA_ERROR = -1, MCA_ERR_OUT_OF_RESOURCE = -2, MCA_ERR_TEMP_OUT_OF_RESOURCE = -3,
  MCA_ERR_BAD_PARAM = -5, MCA_ERR_NOT_IMPLEMENTED = -10, MCA_ERR_NOT_SUPPORTED = -11, MCA_MAX_ERROR = -20
}
 MCA return codes. More...
 

Detailed Description

Top-level interface for all MCA components.

Historical notes:

Open MPI originally used a v1.0.0 of the MCA component structs, but did not have a version number in the struct name. If I recall correctly, this is because we simply didn't think through (or never envisioned) changing the MCA base component struct itself. Oops.

We made some changes in the base struct in Open MPI v1.3, and decided the following at the same time:

  • Bump the MCA version number to 2.0.0 and add some "reserved" space at the end of the struct.
  • The major MCA version number is essentially tied to the space that the struct occupies; if we make future changes in the struct by just using some of the reserved space, it may be possible to just increment the minor version number (depending on the scope of the change). If we need to add more space to the struct, we'll increment the major version number.
  • The MCA base component struct now has a version number in it (starting with Open MPI v1.3, it is 2.0.0).
  • As was an unstated assumption in prior versions of Open MPI, the unversioned versions of struct names (both in the MCA base and in individual framework bases) are intended for components who want to be forward source-compatible. That is, the unversioned struct name always represents the most recent interface version. If you need to use an older version, you can explicitly use that older struct version name. Please note, however, the Open MPI developers may not generally provide older versions of framework interface structs unless they know if someone outside of the Open MPI community needs it.

    ***IF YOU NEED BACKWARDS SOURCE OR BINARY COMPATIBILITY, you must let us know!***

  • We are currently only aware of one external developer making Open MPI components for the v1.2 series. He already knows that there are major changes coming in the v1.3 series, and does not expect to be able to use his v1.2 DSO binaries in v1.3. As such, we are breaking backwards binary compatibility in v1.3: there is no possibility of loading an MCA v1.0 binary component in Open MPI v1.3 or beyond (source compatibility is much easier – the binary "refuse to load MCA components <v2.0.0" policy is enforced in mca_base_component_find.c).

    ***IF YOU NEED BACKWARDS BINARY COMPATIBILITY, please let us know!***

  • Note that we decided that framework version numbers are not related to the MCA version number. It is permissible to bump the MCA version number and leave all the framework version numbers they same. Specifically: a component is uniquely identified by its (MCA version, framework version, component version) tuple. So a component that is simply compiled with two different MCA base versions is still considered "different" because the tuple first member is different.
  • Per the discussion above, we decided to have MCA v2.0 no longer load <v2.0.0 components, and therefore avoided the "how to upcast a component in memory" issue. After v2.0.0, it is slightly easier because the MCA component structs have "reserved" space at the end that may account for future version data fields.

Macro Definition Documentation

#define MCA_BASE_VERSION_MAJOR   2

Macro for framework author convenience.

This macro is used by frameworks defining their component types, indicating that they subscribe to the MCA version 2.0.0. See component header files (e.g., coll.h) for examples of its usage.

Typedef Documentation

typedef int(* mca_base_close_component_1_0_0_fn_t)(void)

MCA component close function.

Return values
MCA_SUCCESSThe component successfully shut down.
any_other_valueSome error occurred, but is likely to be ignored.

This function is invoked on a component after all of its modules have been finalized (according to the rules of its framework) and the component will never be used in the process again; the component may be unloaded from the process memory after the close function has been invoked.

This function is typically used to release any resources still in use by the component.

If the component has no resources to free, it may provide NULL for this function. In this case, the MCA will act as if it called the close function and it returned MCA_SUCCESS.

typedef int(* mca_base_open_component_1_0_0_fn_t)(void)

MCA component open function.

Return values
MCA_SUCCESS(or OPAL_SUCCESS or ORTE_SUCCESS or OMPI_SUCCESS) This component can be used in the process.
OPAL_ERR_NOT_AVAILABLESilently ignore this component for the duration of the process (it may even be unloaded from the process).
anything_elseThe MCA base will print an error message ignore this component for the duration of the process (it may even be unloaded from the process).

All MCA components can have an "open" function that is invoked once per process, when the component is located and loaded. This function should register any MCA parameters (using mca_base_param_register_int() and mca_base_param_register_string()) that will be used by the component. Parameter registrations should occur in this function because the ompi_info command can be used by users to display all available MCA parameters (and their default values). However, the ompi_info command only invokes this open function on all components (i.e., no other component API methods).

This function can also be used to allocate any resources necessary for the component (e.g., heap memory).

This function should return MCA_SUCCESS if it wishes to remain loaded in the process. Any other return value will cause the MCA base to unload the component. Although most components do not use this mechanism to force themselves to be unloaded (because if they are immediately unloaded, ompi_info will not display them), the mechanism is available should the need arise.

If the component a) has no MCA parameters to register, b) no resources to allocate, and c) can always be used in a process (albiet perhaps not selected), it may provide NULL for this function. In this cause, the MCA will act as if it called the open function and it returned MCA_SUCCESS.

typedef int(* mca_base_query_component_2_0_0_fn_t)(mca_base_module_2_0_0_t **module, int *priority)

MCA component query function.

Return values
OPAL_SUCCESSThe component successfully queried.
any_other_valueSome error occurred, but is likely to be ignored.
Parameters
moduleThe module to be used if this component is selected.
priorityThe priority of this component.

This function is used by the mca_base_select function to find the highest priority component to select. Frameworks are free to implement their own query function, but must also implment their own select function as a result.

typedef int(* mca_base_register_component_params_2_0_0_fn_t)(void)

MCA component parameter registration function.

Return values
MCA_SUCCESSThis component successfully registered its parameters and can be used in this process.
anything_elseThe MCA will ignore this component for the duration of the process.

If a component has a non-NULL parameter registration function, it will be invoked to register all MCA parameters associated with the component. This function is invoked before the component "open" function is invoked.

The registration function should not allocate any resources that need to be freed (aside from registering MCA parameters). Specifically, strings that are passed to the MCA parameter registration functions are all internally copied; there's no need for the caller to keep them after registering a parameter. Hence, it is possible that the registration function will be the only function invoked on a component; component authors should take care that no resources are leaked in this case.

This function should return MCA_SUCCESS if it wishes to remain loaded in the process. Any other return value will cause the MCA base to unload the component. Although most components do not use this mechanism to force themselves to be unloaded (because if they are immediately unloaded, ompi_info will not display them), the mechanism is available should the need arise.

If the component a) has no MCA parameters to register, b) no resources to allocate, and c) can always be used in a process (albiet perhaps not selected), it may provide NULL for this function. In this cause, the MCA will act as if it called the registration function and it returned MCA_SUCCESS.

Enumeration Type Documentation

anonymous enum

MCA return codes.

Enumerator
MCA_SUCCESS 

Success.

MCA_ERROR 

General error.

MCA_ERR_OUT_OF_RESOURCE 

Out of resources; a fatal error.

MCA_ERR_TEMP_OUT_OF_RESOURCE 

Out of resources; try again later.

MCA_ERR_BAD_PARAM 

Equivalent to MPI_ERR_ARG error code.

MCA_ERR_NOT_IMPLEMENTED 

Returned by functions or functionality that has not yet been implemented.

MCA_ERR_NOT_SUPPORTED 

Returned by functionality that is not supported.

MCA_MAX_ERROR 

Maximum error code.