


Up:  File Manipulation
Next:  Reserved File Hints
Previous:  Querying File Parameters
  
 
Hints specified via info  
(see Section 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.  
However, hints do not change the semantics of any of the I/O interfaces.  
In other words, an implementation is free to ignore all hints.  
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.  
 
 
 
 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.  
  
Needless to say, no hint can be mandatory.  
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(fh, info) | 
  
| INOUT fh | file handle (handle) | 
  
| IN info | info object (handle) | 
  
  
 
  int MPI_File_set_info(MPI_File fh, MPI_Info info) 
  
  MPI_FILE_SET_INFO(FH, INFO, IERROR)
 INTEGER FH, INFO, IERROR 
  
  void MPI::File::Set_info(const MPI::Info& info) 
  
 
 MPI_FILE_SET_INFO sets new values for the hints  
of the file associated with  fh.  
  
 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.  
 ( End of advice to users.) 
 
| MPI_FILE_GET_INFO(fh, info_used) | 
  
| IN fh | file handle (handle) | 
  
| OUT info_used | new info object (handle) | 
  
  
 
  int MPI_File_get_info(MPI_File fh, MPI_Info *info_used) 
  
  MPI_FILE_GET_INFO(FH, INFO_USED, IERROR)
 INTEGER FH, INFO_USED, IERROR 
  
  
  MPI::Info MPI::File::Get_info() const 
  
  
 
 MPI_FILE_GET_INFO returns a new info object containing  
the hints  
of the file associated with  fh.  
  
The current setting of all hints actually used by the system  
related to this open file is returned in  info_used.  
The user is responsible for freeing  info_used  
via  MPI_INFO_FREE.  
 
 
 
 Advice to users.  
 
The info object returned in  info_used will contain all  
hints currently active for this file.  
This set of hints may be greater or smaller than the set of hints passed  
in to  MPI_FILE_OPEN,  
 MPI_FILE_SET_VIEW, and  MPI_FILE_SET_INFO,  
as the system may not recognize some hints set by the user,  
and may recognize other hints that the user has not set.  
 ( End of advice to users.) 
 
 



Up:  File Manipulation
Next:  Reserved File Hints
Previous:  Querying File Parameters



Up:  File Info
Next:  File Views
Previous:  File Info
  
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 Section 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.  
  
Legal 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 multidimentional  
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 legal 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 run programs that 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.  
 
 
 



Up:  File Info
Next:  File Views
Previous:  File Info
Return to MPI-2 Standard Index
Return to MPI Standard Index
Return to MPI Forum Home Page
Return to MPI Home Page
MPI-2.0 of July 18, 1997
HTML Generated on November 1, 2000