15.2.8. File Info

Hints specified via info (see Chapter The Info Object) allow a user to provide information such as file access patterns and file system specifics to direct optimization. Providing hints may enable an implementation to deliver increased I/O performance or minimize the use of system resources. As described in Section The Info Object, an implementation is free to ignore all hints; however, applications must comply with any info hints they provide that are used by the MPI implementation (i.e., are returned by a call to MPI_FILE_GET_INFO) and that place a restriction on the behavior of the application. Hints are specified on a per file basis, in MPI_FILE_OPEN, MPI_FILE_DELETE, MPI_FILE_SET_VIEW, and MPI_FILE_SET_INFO, via the opaque info object. When an info object that specifies a subset of valid hints is passed to MPI_FILE_SET_VIEW or MPI_FILE_SET_INFO, there will be no effect on previously set or defaulted hints that the info does not specify.

Advice to implementors.

It may happen that a program is coded with hints for one system, and later executes on another system that does not support these hints. In general, unsupported hints should simply be ignored.

However, for each hint used by a specific implementation, a default value must be provided when the user does not specify a value for this hint. ( End of advice to implementors.)

MPI_FILE_SET_INFO updates the hints of the file associated with fh using the hints provided in info. This operation has no effect on previously set or defaulted hints that are not specified by info. It also has no effect on previously set or defaulted hints that are specified by info, but are ignored by the MPI implementation in this call to MPI_FILE_SET_INFO. MPI_FILE_SET_INFO is a collective routine. The info object may be different on each process, but any info entries that an implementation requires to be the same on all processes must appear with the same value in each process's info object.

Advice to users.

Many info items that an implementation can use when it creates or opens a file cannot easily be changed once the file has been created or opened. Thus, an implementation may ignore hints issued in this call that it would have accepted in an open call. An implementation may also be unable to update certain info hints in a call to MPI_FILE_SET_VIEW or MPI_FILE_SET_INFO. MPI_FILE_GET_INFO can be used to determine whether info changes were ignored by the implementation. ( End of advice to users.)

MPI_FILE_GET_INFO returns a new info object containing the hints of the file associated with fh. The current setting of all hints related to this file is returned in info_used. An MPI implementation is required to return all hints that are supported by the implementation and have default values specified; any user-supplied hints that were not ignored by the implementation; and any additional hints that were set by the implementation. If no such hints exist, a handle to a newly created info object is returned that contains no (key,value) pairs. The user is responsible for freeing info_used via MPI_INFO_FREE.

15.2.8.1. Reserved File Hints

Some potentially useful hints (info key values) are outlined below. The following key values are reserved. An implementation is not required to interpret these key values, but if it does interpret the key value, it must provide the functionality described. (For more details on ``info,'' see Chapter The Info Object.)

These hints mainly affect access patterns and the layout of data on parallel I/O devices. For each hint name introduced, we describe the purpose of the hint, and the type of the hint value. The `` [SAME]'' annotation specifies that the hint values provided by all participating processes must be identical; otherwise the program is erroneous. In addition, some hints are context dependent, and are only used by an implementation at specific times (e.g., file_perm is only useful during file creation).

"access_style" (comma separated list of strings):

This hint specifies the manner in which the file will be accessed until the file is closed or until the access_style key value is altered. The hint value is a comma separated list of the following: "read_once", "write_once", "read_mostly", "write_mostly", "sequential", "reverse_sequential", and "random".

"collective_buffering" (boolean) SAME:

This hint specifies whether the application may benefit from collective buffering. Collective buffering is an optimization performed on collective accesses. Accesses to the file are performed on behalf of all processes in the group by a number of target nodes. These target nodes coalesce small requests into large disk accesses. Valid values for this key are true and false. Collective buffering parameters are further directed via additional hints: cb_block_size, cb_buffer_size, and cb_nodes.

"cb_block_size" (integer) SAME:

This hint specifies the block size to be used for collective buffering file access. Target nodes access data in chunks of this size. The chunks are distributed among target nodes in a round-robin (cyclic) pattern.

"cb_buffer_size" (integer) SAME:

This hint specifies the total buffer space that can be used for collective buffering on each target node, usually a multiple of cb_block_size.

"cb_nodes" (integer) SAME:

This hint specifies the number of target nodes to be used for collective buffering.

"chunked" (comma separated list of integers) SAME:

This hint specifies that the file consists of a multidimensional array that is often accessed by subarrays. The value for this hint is a comma separated list of array dimensions, starting from the most significant one (for an array stored in row-major order, as in C, the most significant dimension is the first one; for an array stored in column-major order, as in Fortran, the most significant dimension is the last one, and array dimensions should be reversed).

"chunked_item" (comma separated list of integers) SAME:

This hint specifies the size of each array entry, in bytes.

"chunked_size" (comma separated list of integers) SAME:

This hint specifies the dimensions of the subarrays. This is a comma separated list of array dimensions, starting from the most significant one.

"filename" (string):

This hint specifies the file name used when the file was opened. If the implementation is capable of returning the file name of an open file, it will be returned using this key by MPI_FILE_GET_INFO. This key is ignored when passed to MPI_FILE_OPEN, MPI_FILE_SET_VIEW, MPI_FILE_SET_INFO, and MPI_FILE_DELETE.

"file_perm" (string) SAME:

This hint specifies the file permissions to use for file creation. Setting this hint is only useful when passed to MPI_FILE_OPEN with an amode that includes MPI_MODE_CREATE. The set of valid values for this key is implementation dependent.

"io_node_list" (comma separated list of strings) SAME:

This hint specifies the list of I/O devices that should be used to store the file. This hint is most relevant when the file is created.

"nb_proc" (integer) SAME:

This hint specifies the number of parallel processes that will typically be assigned to access this file. This hint is most relevant when the file is created.

"num_io_nodes" (integer) SAME:

This hint specifies the number of I/O devices in the system. This hint is most relevant when the file is created.

"striping_factor" (integer) SAME:

This hint specifies the number of I/O devices that the file should be striped across, and is relevant only when the file is created.

"striping_unit" (integer) SAME:

This hint specifies the suggested striping unit to be used for this file. The striping unit is the amount of consecutive data assigned to one I/O device before progressing to the next device, when striping across a number of devices. It is expressed in bytes. This hint is relevant only when the file is created.

mpi_assert_memory_alloc_kinds (string, not set by default):

If set, the implementation may assume that the memory for all data buffers passed to MPI operations performed by the calling MPI process on the given file will use only the memory allocation kinds listed in the value string. See Section Memory Allocation Info.