OpenMPI  0.1.1
base.h File Reference

MCA io base framework public interface functions. More...

#include "ompi_config.h"
#include "mpi.h"
#include "opal/class/opal_list.h"
#include "ompi/class/ompi_free_list.h"
#include "ompi/mca/io/io.h"

Go to the source code of this file.

Functions

BEGIN_C_DECLS OMPI_DECLSPEC int mca_io_base_open (void)
 Initialize the io MCA framework. More...
 
OMPI_DECLSPEC int mca_io_base_find_available (bool enable_progress_threads, bool enable_mpi_threads)
 Create list of available io components. More...
 
OMPI_DECLSPEC int mca_io_base_file_select (struct ompi_file_t *file, mca_base_component_t *preferred)
 Select an available component for a new file handle. More...
 
OMPI_DECLSPEC int mca_io_base_file_unselect (struct ompi_file_t *file)
 Finalize a io component on a specific file handle. More...
 
OMPI_DECLSPEC int mca_io_base_delete (char *filename, struct ompi_info_t *info)
 Invoke a back-end component to delete a file. More...
 
OMPI_DECLSPEC int mca_io_base_close (void)
 Shut down the io MCA framework. More...
 
OMPI_DECLSPEC int mca_io_base_register_datarep (char *, MPI_Datarep_conversion_function *, MPI_Datarep_conversion_function *, MPI_Datarep_extent_function *, void *)
 

Variables

OMPI_DECLSPEC int mca_io_base_param
 Index number from the "io" MCA parameter, created when the io framework is initialized and used during scope selection.
 
OMPI_DECLSPEC int mca_io_base_output
 io framework debugging stream ID used with opal_output() and opal_output_verbose().
 
OMPI_DECLSPEC bool mca_io_base_components_opened_valid
 Indicator as to whether the list of opened io components is valid or not.
 
OMPI_DECLSPEC opal_list_t mca_io_base_components_opened
 List of all opened components; created when the io framework is initialized and destroyed when we reduce the list to all available io components.
 
OMPI_DECLSPEC bool mca_io_base_components_available_valid
 Indicator as to whether the list of available io components is valid or not.
 
OMPI_DECLSPEC opal_list_t mca_io_base_components_available
 List of all available components; created by reducing the list of open components to all those who indicate that they may run during this process.
 

Detailed Description

MCA io base framework public interface functions.

Function Documentation

OMPI_DECLSPEC int mca_io_base_close ( void  )

Shut down the io MCA framework.

Return values
OMPI_SUCCESSAlways

This function shuts down everything in the io MCA framework, and is called during ompi_mpi_finalize() and the special case of the laminfo fileand.

It must be the last function invoked on the io MCA framework.

References mca_io_base_components_available, mca_io_base_components_available_valid, mca_io_base_components_opened, mca_io_base_components_opened_valid, mca_io_base_output, and OBJ_DESTRUCT.

Referenced by ompi_mpi_finalize().

OMPI_DECLSPEC int mca_io_base_delete ( char *  filename,
struct ompi_info_t info 
)

Invoke a back-end component to delete a file.

Parameters
filenameName of the file to be deleted
infoMPI_Info for additional information

This function is a bit different than most other MPI_File_* functions – it does not take a MPI_File handle. As such, this function function invokes appropriate delete handlers on all the available components (rather than some pre-selected module). See io.h for details.

References mca_base_param_lookup_string(), mca_base_component_2_0_0_t::mca_component_name, mca_io_base_components_available, mca_io_base_output, mca_io_base_param, OBJ_RELEASE, opal_argv_count(), opal_argv_free(), opal_argv_split(), opal_list_remove_first(), opal_list_remove_last(), and opal_output_verbose().

OMPI_DECLSPEC int mca_io_base_file_select ( struct ompi_file_t file,
mca_base_component_t preferred 
)

Select an available component for a new file handle.

Parameters
fileFile Handle that the component will be selected for.
preferredThe component that is preferred for this file handle (or NULL).
Returns
OMPI_SUCCESS Upon success.
OMPI_ERROR Upon failure.

Note that the types of the parameters have "struct" in them (e.g., ompi_file_t" vs. a plain "ompi_file_t") to avoid an include file loop. All similar types (e.g., "struct ompi_file_t *", "ompi_file_t *", and "MPI_File") are all typedef'ed to be the same, so the fact that we use struct here in the prototype is ok.

This function is invoked when a new file handle is created and a io component needs to be selected for it. It should be invoked near the end of the file handle creation process such that almost everything else is functional on the file handle.

This function invokes the selection process for io components, which works as follows:

  • If the preferred argument is NULL, the selection set is defined to be all the components found during mca_io_base_find_available().
  • If preferred is not NULL, then the selection set is just that component. (However, in this mode, we may make 2 passes through the selection process – more on this below).
  • All components in the selection set are queried to see if they want to run with that file handle. All components that want to run are ranked by their priority and the highest priority component is selected. All non-selected components have their "unquery" function invoked to let them know that they were not selected.
  • The selected module will have its "init" function invoked to let it know that it was selected. All unselected components will have their file_unselect function invoked.
  • If we fall through this entire process and no component is selected and the preferred argument is not NULL, then run the entire process again as if the preferred argument was NULL (i.e., use the entire available set of components).

At the end of this process, we'll either have a single component/module pair that is selected and initialized for the file handle, or no component was selected and an error is returned up the stack.

References ompi_file_t::f_filename, ompi_file_t::f_io_selected_component, ompi_file_t::f_io_selected_data, ompi_file_t::f_io_selected_module, ompi_file_t::f_io_version, mca_base_param_lookup_string(), mca_base_component_2_0_0_t::mca_component_name, mca_io_base_components_available, mca_io_base_output, mca_io_base_param, OBJ_RELEASE, opal_argv_count(), opal_argv_free(), opal_argv_split(), opal_list_remove_first(), opal_list_remove_last(), and opal_output_verbose().

OMPI_DECLSPEC int mca_io_base_file_unselect ( struct ompi_file_t file)

Finalize a io component on a specific file handle.

Parameters
fileThe file handle that is being destroyed.
Return values
OMPI_SUCCESSAlways.

Note that the type of the parameter is only a "struct ompi_file_t" (vs. a plain "ompi_file_t") to avoid an include file loop. The types "struct ompi_file_t *", "ompi_file_t *", and "MPI_File" are all typedef'ed to be the same, so the fact that we use struct here in the prototype is ok.

This function is invoked near the beginning of the destruction of a file handle. It finalizes the io component associated with the file handle (e.g., allowing the component to clean up and free any resources allocated for that file handle). Note that similar to mca_io_base_select(), as result of this function, other file handles may also be destroyed.

OMPI_DECLSPEC int mca_io_base_find_available ( bool  enable_progress_threads,
bool  enable_mpi_threads 
)

Create list of available io components.

Parameters
allow_multi_user_threadsWill be set to true if any of the available components will allow multiple user threads
have_hidden_threadsWill be set to true if any of the available components have hidden threads.
Return values
OMPI_SUCCESSIf one or more io components are available.
OMPI_ERRORIf no io components are found to be available.

This function is invoked during ompi_mpi_init() to query all successfully opened io components and create a list of all available io components.

This function traverses the (internal global variable) mca_io_base_components_opened list and queries each component to see if it ever might want to run during this MPI process. It creates another internal global variable list named mca_io_base_components_available, consisting of a list of components that are available for selection when file handles are created. This variable should only be used by other io base functions – it is not considered a public interface member – and is only mentioned here for completeness.

References mca_io_base_components_available, mca_io_base_components_available_valid, mca_io_base_components_opened, mca_io_base_components_opened_valid, OBJ_CONSTRUCT, OBJ_DESTRUCT, OBJ_RELEASE, opal_list_append, and opal_list_remove_first().

BEGIN_C_DECLS OMPI_DECLSPEC int mca_io_base_open ( void  )

Initialize the io MCA framework.

Return values
OMPI_SUCCESSUpon success
OMPI_ERRORUpon failure

This must be the first function invoked in the io MCA framework. It initializes the io MCA framework, finds and opens io components, etc.

This function is invoked during ompi_mpi_init() and during the initialization of the special case of the laminfo command.

This function fills in the internal global variable mca_io_base_components_opened, which is a list of all io components that were successfully opened. This variable should only be used by other io base functions – it is not considered a public interface member – and is only mentioned here for completeness.

References mca_base_param_find(), mca_base_param_reg_int_name(), mca_io_base_components_opened_valid, mca_io_base_output, mca_io_base_param, and opal_output_open().