Distributed File Input/Output class. More...

#include <dist_file_io.hpp>

Static Public Member Functions
static void	read_combined (BinaryStream &common, BinaryStream &buffer, const String &filename, const Dist::Comm &comm, int root_rank=0, bool bcast_common=true)
	Reads a combined shared/ordered binary file as written by the write_combined function. More...

static void	read_combined (std::vector< char > &common, std::vector< char > &buffer, const String &filename, const Dist::Comm &comm, int root_rank=0, bool bcast_common=true)
	Reads a combined shared/ordered binary file as written by the write_combined function. More...

static void	read_common (BinaryStream &stream, const String &filename)
	Reads a common text file for all ranks. More...

static void	read_common (BinaryStream &stream, const String &filename, const Dist::Comm &comm, int root_rank=0)
	Reads a common binary file for all ranks. More...

static void	read_common (std::stringstream &stream, const String &filename)
	Reads a common text file for all ranks. More...

static void	read_common (std::stringstream &stream, const String &filename, const Dist::Comm &comm, int root_rank=0)
	Reads a common text file for all ranks. More...

static void	read_ordered (void *buffer, const std::size_t size, const String &filename)
	Reads a buffer from a common binary file in rank order. More...

static void	read_ordered (void *buffer, const std::size_t size, const String &filename, const Dist::Comm &comm)
	Reads a buffer from a common binary file in rank order. More...

static void	read_sequence (BinaryStream &stream, const String &pattern)
	Reads a rank-indexed text file sequence. More...

static void	read_sequence (BinaryStream &stream, const String &pattern, const Dist::Comm &comm)
	Reads a rank-indexed binary file sequence. More...

static void	read_sequence (std::stringstream &stream, const String &pattern)
	Reads a rank-indexed text file sequence. More...

static void	read_sequence (std::stringstream &stream, const String &pattern, const Dist::Comm &comm)
	Reads a rank-indexed text file sequence. More...

static void	write_combined (const BinaryStream &common, const BinaryStream &buffer, const String &filename, const Dist::Comm &comm, int root_rank=0)
	Writes a combined shared/ordered binary file. More...

static void	write_combined (const std::vector< char > &common, const std::vector< char > &buffer, const String &filename, const Dist::Comm &comm, int root_rank=0)
	Writes a combined shared/ordered binary file. More...

static void	write_ordered (BinaryStream &stream, const String &filename, bool truncate=true)
	Writes a buffer into a common binary file in rank order. More...

static void	write_ordered (BinaryStream &stream, const String &filename, const Dist::Comm &comm, bool truncate=true)
	Writes a binary stream into a common binary file in rank order. More...

static void	write_ordered (const void *buffer, const std::size_t size, const String &filename, bool truncate=true)
	Writes a buffer into a common binary file in rank order. More...

static void	write_ordered (const void *buffer, const std::size_t size, const String &filename, const Dist::Comm &comm, bool truncate=true)
	Writes a buffer into a common binary file in rank order. More...

static void	write_sequence (BinaryStream &stream, const String &pattern, bool truncate=true)
	Writes a rank-indexed text file sequence. More...

static void	write_sequence (BinaryStream &stream, const String &pattern, const Dist::Comm &comm, bool truncate=true)
	Writes a rank-indexed binary file sequence. More...

static void	write_sequence (std::stringstream &stream, const String &pattern, bool truncate=true)
	Writes a rank-indexed text file sequence. More...

static void	write_sequence (std::stringstream &stream, const String &pattern, const Dist::Comm &comm, bool truncate=true)
	Writes a rank-indexed text file sequence. More...

Static Public Attributes
static constexpr std::uint64_t	magic_combined = 0x4644433354414546ull
	Magic number for combined distributed files as used by read_combined() and write_combined() More...

Static Protected Member Functions
static String	_rankname (const String &pattern, int rank)
	auxiliary function: build a rank filename from a pattern More...

static void	_read_file (BinaryStream &stream, const String &filename)
	auxiliary function: read a file into a binary stream More...

static void	_read_file (std::stringstream &stream, const String &filename)
	auxiliary function: read a file into a string stream More...

static void	_write_file (BinaryStream &stream, const String &filename, bool truncate)
	auxiliary function: write a binary stream to a file More...

static void	_write_file (std::stringstream &stream, const String &filename, bool truncate)
	auxiliary function: write a string stream to a file More...

Detailed Description

Distributed File Input/Output class.

This class implements various static functions for reading and writing files in text or binary mode in a distributed (i.e. parallel) build.

There are three basic sets of functions for reading files as well as a combined version:

read_common: one process reads a single text or binary file and broadcasts its contents to all other processes
read_sequence: each process reads a single text or binary file, which is indexed by the process rank
read_ordered: all processes read from a single common binary file, ordered by ranks, and using the official MPI I/O routines
read_combined: all processes read from a single common binary file which contains a common data block, which is read by all processes, as well as a private data block, that is read by each process individually using a combination of the official MPI I/O routines. See the corresponding remarks section below for details.

Moreover, there are two sets of functions for writing files:

write_sequence: each process writes a single text or binary file, which is indexed by the process rank
write_ordered: all processes write into a single common binary file, ordered by ranks, and using the official MPI I/O routines
write_combined: all processes write into a single common binary file, which contains a common data block as well as a private data block, that is written by each process ordered by ranks using a combination of the official MPI I/O routines. See the corresponding remarks section below for details.

Each common/sequence function comes in two overloads: one for objects of type std::stringstream for text files and another one for objects of type BinaryStream for binary files.

Remarks regarding Sequence I/O functions:
For both the read_sequence and write_sequence functions, one specifies a filename pattern which is used as a template for the generation of the filename for each rank. The filename pattern has to contain a continuous block of asterisks (*), which serves as a place-holder for the 0-padded rank number.

Example:
If pattern is ./my_file_****.txt, then

rank 0 reads/writes the file ./my_file_0000.txt
rank 1 reads/writes the file ./my_file_0001.txt
rank 2 reads/writes the file ./my_file_0002.txt
etc.

Remarks regarding Combined I/O functions:
In contrast to the write_ordered() functions also offered by this class, the write_combined() function does not simply write out the raw data arrays to the file, but it also writes out a simple file header including all the required array size informations for each data array. In consequence, when reading in a file using the read_combined() function, it is not necessary to allocate the output buffer for each process beforehand (as opposed to the read_ordered() function) because the required buffer size is automatically read from file.

In addition to that, the combined data file can also contain a common data array, which is automatically broadcasted to all processes by the read_combined() function upon reading. This common data array can be used to store information that is identical for all processes and therefore does not need to be stored by each process individually to reduce redundancy within the file and therefore reduce the total file size. When calling the write_combined() function, the caller can decide which process (called "root") is responsible for writing out the common data array.

The binary output file is composed of four sections or chunks:

  +---+---+---+---+
  | H | S | C | P |
  +---+---+---+---+

'H': a 32-byte file header which consists of four uint64 entries:
- the file magic, which must be equal to magic_combined = "FEAT3CDF"
- the total filesize in bytes
- the number of processes that were used to write the file
- the size of the common buffer in bytes
'S': an uint64 array which contains the sizes of the process data arrays in bytes
'C': the raw common data array, may be empty
'P': the data arrays from each process, ordered by ranks

Assume we have (n+1) processes and each process has an identical copy of a common data array C of size SC := sizeof(C) bytes as well as a private data array Pk of size Sk := sizeof(Pk) bytes:

 +--------+   +--------+   +--------+       +--------+
 | Rank 0 |   | Rank 1 |   | Rank 2 |       | Rank n |
 | C | P0 |   | C | P1 |   | C | P2 |  ...  | C | Pn |
 +--------+   +--------+   +--------+       +--------+
  \_/ \__/     \_/ \__/     \_/ \__/         \_/ \__/
  SC   S0      SC   S1      SC   S2          SC   Sn
   bytes        bytes        bytes            bytes

The corresponding binary output file created by the write_combined() function will have a total fizesize of 32 + 8*(n+1) + SC + S0 + S1 + S2 + ... + Sn bytes:

 +--------+-----------------+----------+----------+----------+-----+----------+
 | Header | S0 S1 S2 ... Sn |    C     |    P0    |    P1    | ... |    Pn    |
 +--------+-----------------+----------+----------+----------+-----+----------+
  \______/ \_______________/ \________/ \________/ \________/       \________/
  32 bytes   8*(n+1) bytes    SC bytes   S0 bytes   S1 bytes   ...   Sn bytes

Author: Peter Zajac

Definition at line 119 of file dist_file_io.hpp.

Member Function Documentation

◆ _rankname()

String FEAT::DistFileIO::_rankname	(	const String &	pattern,
		int	rank
	)

staticprotected

auxiliary function: build a rank filename from a pattern

Definition at line 14 of file dist_file_io.cpp.

References FEAT::String::pad_front(), FEAT::stringify(), and XASSERTM.

Referenced by read_sequence(), and write_sequence().

◆ _read_file() [1/2]

void FEAT::DistFileIO::_read_file	(	BinaryStream &	stream,
		const String &	filename
	)

staticprotected

auxiliary function: read a file into a binary stream

Definition at line 53 of file dist_file_io.cpp.

References FEAT::BinaryStream::read_stream(), and XASSERT.

◆ _read_file() [2/2]

void FEAT::DistFileIO::_read_file	(	std::stringstream &	stream,
		const String &	filename
	)

staticprotected

auxiliary function: read a file into a string stream

Definition at line 36 of file dist_file_io.cpp.

References XASSERT.

Referenced by read_common(), and read_sequence().

◆ _write_file() [1/2]

void FEAT::DistFileIO::_write_file	(	BinaryStream &	stream,
		const String &	filename,
		bool	truncate
	)

staticprotected

auxiliary function: write a binary stream to a file

Definition at line 89 of file dist_file_io.cpp.

References FEAT::BinaryStream::write_stream().

◆ _write_file() [2/2]

void FEAT::DistFileIO::_write_file	(	std::stringstream &	stream,
		const String &	filename,
		bool	truncate
	)

staticprotected

auxiliary function: write a string stream to a file

Definition at line 70 of file dist_file_io.cpp.

Referenced by write_sequence().

◆ read_combined() [1/2]

static void FEAT::DistFileIO::read_combined	(	BinaryStream &	common,
		BinaryStream &	buffer,
		const String &	filename,
		const Dist::Comm &	comm,
		int	root_rank = `0`,
		bool	bcast_common = `true`
	)

inlinestatic

Reads a combined shared/ordered binary file as written by the write_combined function.

This function reads a single binary file, which contains both a common buffer, that is shared amongst all processes, as well one private buffer for each individual process.

Parameters

[out]	common	A byte-vector that receives the common buffer whose contents are to be read from the file. This vector is allocated to its correct size by this function. Depending on the value of the parameter `bcast_common`, this common buffer in only filled on the root process (`bcast_common = false`) or it is filled (broadcasted) onto all processes (`bcast_common = true`).
[out]	buffer	A byte-vector that receives the individual buffer which is read from file by each process. This vector is allocated to its correct size on each process by this function.
[in]	filename	The name of the common output file. Must be the same on all calling processes.
[in]	comm	The communicator to be used for synchronization. Ignored if compiled without MPI.
[in]	root_rank	Specifies which process should actually read the file. Ignored if compiled without MPI.
[in]	bcast_common	Specifies whether the shared buffer is to be broadcasted to all processes or whether it is only filled on the root process. Ignored if compiled without MPI.

Definition at line 414 of file dist_file_io.hpp.

References FEAT::BinaryStream::container(), and read_combined().

◆ read_combined() [2/2]

void FEAT::DistFileIO::read_combined	(	std::vector< char > &	common,
		std::vector< char > &	buffer,
		const String &	filename,
		const Dist::Comm &	comm,
		int	root_rank = `0`,
		bool	bcast_common = `true`
	)

static

Reads a combined shared/ordered binary file as written by the write_combined function.

This function reads a single binary file, which contains both a common buffer, that is shared amongst all processes, as well one private buffer for each individual process.

Parameters

[out]	common	A byte-vector that receives the common buffer whose contents are to be read from the file. This vector is allocated to its correct size by this function. Depending on the value of the parameter `bcast_common`, this common buffer in only filled on the root process (`bcast_common = false`) or it is filled (broadcasted) onto all processes (`bcast_common = true`).
[out]	buffer	A byte-vector that receives the individual buffer which is read from file by each process. This vector is allocated to its correct size on each process by this function.
[in]	filename	The name of the common output file. Must be the same on all calling processes.
[in]	comm	The communicator to be used for synchronization. Ignored if compiled without MPI.
[in]	root_rank	Specifies which process should actually read the file. Ignored if compiled without MPI.
[in]	bcast_common	Specifies whether the shared buffer is to be broadcasted to all processes or whether it is only filled on the root process. Ignored if compiled without MPI.

Definition at line 490 of file dist_file_io.cpp.

References magic_combined, FEAT::stringify(), and XASSERTM.

Referenced by FEAT::Control::CheckpointControl::_load(), and read_combined().

◆ read_common() [1/4]

static void FEAT::DistFileIO::read_common	(	BinaryStream &	stream,
		const String &	filename
	)

inlinestatic

Reads a common text file for all ranks.

This function reads a single file on the root rank and broadcasts its contents to all other ranks.

Parameters

[out]	stream	A transient reference to the string stream that receives the file contents.
[in]	filename	The name of the file to be read.
[in]	comm	The communicator to be used for synchronization. Ignored if compiled without MPI.
[in]	root_rank	Specifies which rank should actually read the file. Ignored if compiled without MPI.

Exceptions

FileNotFound if the file could not be opened.

Definition at line 179 of file dist_file_io.hpp.

References read_common(), and FEAT::Dist::Comm::world().

◆ read_common() [2/4]

void FEAT::DistFileIO::read_common	(	BinaryStream &	stream,
		const String &	filename,
		const Dist::Comm &	comm,
		int	root_rank = `0`
	)

static

Reads a common binary file for all ranks.

This function reads a single file on the root rank and broadcasts its contents to all other ranks.

Parameters

[out]	stream	A transient reference to the binary stream that receives the file contents.
[in]	filename	The name of the file to be read.
[in]	comm	The communicator to be used for synchronization. Ignored if compiled without MPI.
[in]	root_rank	Specifies which rank should actually read the file. Ignored if compiled without MPI.

Exceptions

FileNotFound if the file could not be opened.

Definition at line 419 of file dist_file_io.cpp.

References _read_file().

◆ read_common() [3/4]

static void FEAT::DistFileIO::read_common	(	std::stringstream &	stream,
		const String &	filename
	)

inlinestatic

Reads a common text file for all ranks.

This function reads a single file on the root rank and broadcasts its contents to all other ranks.

Parameters

[out]	stream	A transient reference to the string stream that receives the file contents.
[in]	filename	The name of the file to be read.
[in]	comm	The communicator to be used for synchronization. Ignored if compiled without MPI.
[in]	root_rank	Specifies which rank should actually read the file. Ignored if compiled without MPI.

Exceptions

FileNotFound if the file could not be opened.

Definition at line 151 of file dist_file_io.hpp.

References read_common(), and FEAT::Dist::Comm::world().

◆ read_common() [4/4]

void FEAT::DistFileIO::read_common	(	std::stringstream &	stream,
		const String &	filename,
		const Dist::Comm &	comm,
		int	root_rank = `0`
	)

static

Reads a common text file for all ranks.

This function reads a single file on the root rank and broadcasts its contents to all other ranks.

Parameters

[out]	stream	A transient reference to the string stream that receives the file contents.
[in]	filename	The name of the file to be read.
[in]	comm	The communicator to be used for synchronization. Ignored if compiled without MPI.
[in]	root_rank	Specifies which rank should actually read the file. Ignored if compiled without MPI.

Exceptions

FileNotFound if the file could not be opened.

Definition at line 414 of file dist_file_io.cpp.

References _read_file().

Referenced by FEAT::Geometry::MeshFileReader::add_mesh_files(), FEAT::Geometry::VoxelMap::compute_map_from_off_3d(), FEAT::Control::Domain::VoxelDomainControl< DomainLevel_ >::create_voxel_map_from_off(), FEAT::Geometry::VoxelMap::read(), FEAT::PropertyMap::read(), and read_common().

◆ read_ordered() [1/2]

static void FEAT::DistFileIO::read_ordered	(	void *	buffer,
		const std::size_t	size,
		const String &	filename
	)

inlinestatic

Reads a buffer from a common binary file in rank order.

Note: This function is effectively a wrapper around MPI_File_read_ordered.

Parameters

[out]	buffer	A transient pointer to the binary buffer that is to read into. Must not be `nullptr`.
[in]	size	The size of this process's buffer in bytes. May differ on each process.
[in]	filename	The name of the common input file. Must be the same on all calling processes.
[in]	comm	The communicator to be used for synchronization. Ignored if compiled without MPI.

Definition at line 310 of file dist_file_io.hpp.

References read_ordered(), and FEAT::Dist::Comm::world().

◆ read_ordered() [2/2]

void FEAT::DistFileIO::read_ordered	(	void *	buffer,
		const std::size_t	size,
		const String &	filename,
		const Dist::Comm &	comm
	)

static

Reads a buffer from a common binary file in rank order.

Note: This function is effectively a wrapper around MPI_File_read_ordered.

Parameters

[out]	buffer	A transient pointer to the binary buffer that is to read into. Must not be `nullptr`.
[in]	size	The size of this process's buffer in bytes. May differ on each process.
[in]	filename	The name of the common input file. Must be the same on all calling processes.
[in]	comm	The communicator to be used for synchronization. Ignored if compiled without MPI.

Definition at line 444 of file dist_file_io.cpp.

References XASSERT.

Referenced by read_ordered().

◆ read_sequence() [1/4]

static void FEAT::DistFileIO::read_sequence	(	BinaryStream &	stream,
		const String &	pattern
	)

inlinestatic

Reads a rank-indexed text file sequence.

This function reads a sequence of files, where each rank reads a single indexed file.

Parameters

[out]	stream	A transient reference to the string stream that receives the file contents.
[in]	pattern	The pattern that is to be used for filename generation.
[in]	comm	The communicator to be used for synchronization. Ignored if compiled without MPI.

Exceptions

FileNotFound if the file could not be opened.

Definition at line 230 of file dist_file_io.hpp.

References read_sequence(), and FEAT::Dist::Comm::world().

◆ read_sequence() [2/4]

void FEAT::DistFileIO::read_sequence	(	BinaryStream &	stream,
		const String &	pattern,
		const Dist::Comm &	comm
	)

static

Reads a rank-indexed binary file sequence.

This function reads a sequence of files, where each rank reads a single indexed file.

Parameters

[out]	stream	A transient reference to the binary stream that receives the file contents.
[in]	pattern	The pattern that is to be used for filename generation.
[in]	comm	The communicator to be used for synchronization. Ignored if compiled without MPI.

Exceptions

FileNotFound if the file could not be opened.

Definition at line 429 of file dist_file_io.cpp.

References _rankname(), and _read_file().

◆ read_sequence() [3/4]

static void FEAT::DistFileIO::read_sequence	(	std::stringstream &	stream,
		const String &	pattern
	)

inlinestatic

Reads a rank-indexed text file sequence.

This function reads a sequence of files, where each rank reads a single indexed file.

Parameters

[out]	stream	A transient reference to the string stream that receives the file contents.
[in]	pattern	The pattern that is to be used for filename generation.
[in]	comm	The communicator to be used for synchronization. Ignored if compiled without MPI.

Exceptions

FileNotFound if the file could not be opened.

Definition at line 204 of file dist_file_io.hpp.

References read_sequence(), and FEAT::Dist::Comm::world().

◆ read_sequence() [4/4]

void FEAT::DistFileIO::read_sequence	(	std::stringstream &	stream,
		const String &	pattern,
		const Dist::Comm &	comm
	)

static

Reads a rank-indexed text file sequence.

This function reads a sequence of files, where each rank reads a single indexed file.

Parameters

[out]	stream	A transient reference to the string stream that receives the file contents.
[in]	pattern	The pattern that is to be used for filename generation.
[in]	comm	The communicator to be used for synchronization. Ignored if compiled without MPI.

Exceptions

FileNotFound if the file could not be opened.

Definition at line 424 of file dist_file_io.cpp.

References _rankname(), and _read_file().

Referenced by read_sequence().

◆ write_combined() [1/2]

static void FEAT::DistFileIO::write_combined	(	const BinaryStream &	common,
		const BinaryStream &	buffer,
		const String &	filename,
		const Dist::Comm &	comm,
		int	root_rank = `0`
	)

inlinestatic

Writes a combined shared/ordered binary file.

This function writes a single binary file, which contains both a common buffer, that is shared amongst all processes, as well one private buffer for each individual process.

Parameters

[in]	common	The common buffer whose contents are to be written to the file. This buffer is only required on the root process and is ignored on all other processes.
[in]	buffer	The individual buffer for each process whose contents are to be written to the file. This buffer is required on each process and all process buffers will be written to the file in rank-ascending order.
[in]	filename	The name of the common output file. Must be the same on all calling processes.
[in]	comm	The communicator to be used for synchronization. Ignored if compiled without MPI.
[in]	root_rank	Specifies which rank should actually write the file. Ignored if compiled without MPI.

Definition at line 448 of file dist_file_io.hpp.

References FEAT::BinaryStream::container(), and write_combined().

◆ write_combined() [2/2]

void FEAT::DistFileIO::write_combined	(	const std::vector< char > &	common,
		const std::vector< char > &	buffer,
		const String &	filename,
		const Dist::Comm &	comm,
		int	root_rank = `0`
	)

static

Writes a combined shared/ordered binary file.

This function writes a single binary file, which contains both a common buffer, that is shared amongst all processes, as well one private buffer for each individual process.

Parameters

[in]	common	The common buffer whose contents are to be written to the file. This buffer is only required on the root process and is ignored on all other processes.
[in]	buffer	The individual buffer for each process whose contents are to be written to the file. This buffer is required on each process and all process buffers will be written to the file in rank-ascending order.
[in]	filename	The name of the common output file. Must be the same on all calling processes.
[in]	comm	The communicator to be used for synchronization. Ignored if compiled without MPI.
[in]	root_rank	Specifies which rank should actually write the file. Ignored if compiled without MPI.

Definition at line 541 of file dist_file_io.cpp.

References magic_combined.

Referenced by FEAT::Control::CheckpointControl::_save(), and write_combined().

◆ write_ordered() [1/4]

static void FEAT::DistFileIO::write_ordered	(	BinaryStream &	stream,
		const String &	filename,
		bool	truncate = `true`
	)

inlinestatic

Writes a buffer into a common binary file in rank order.

This function write a single common binary file, where the individual processes write their outputs in ascending order by their rank.

Note: This function is effectively a wrapper around MPI_File_write_ordered.

Parameters

[in]	buffer	A transient pointer to the binary buffer that is to be written. Must not be `nullptr`.
[in]	size	The size of this process's buffer in bytes. May differ on each process.
[in]	filename	The name of the common output file. Must be the same on all calling processes.
[in]	comm	The communicator to be used for synchronization. Ignored if compiled without MPI.
[in]	truncate	Specifies whether the output file(s) are to be truncated to the output size.

Definition at line 374 of file dist_file_io.hpp.

References FEAT::BinaryStream::data(), FEAT::BinaryStream::size(), FEAT::Dist::Comm::world(), and write_ordered().

◆ write_ordered() [2/4]

static void FEAT::DistFileIO::write_ordered	(	BinaryStream &	stream,
		const String &	filename,
		const Dist::Comm &	comm,
		bool	truncate = `true`
	)

inlinestatic

Writes a binary stream into a common binary file in rank order.

This function write a single common binary file, where the individual processes write their outputs in ascending order by their rank.

Note: This function is effectively a wrapper around MPI_File_write_ordered.

Parameters

[in]	stream	A transient reference to the binary stream whose contents are to be written to the file.
[in]	filename	The name of the common output file. Must be the same on all calling processes.
[in]	comm	The communicator to be used for synchronization. Ignored if compiled without MPI.
[in]	truncate	Specifies whether the output file(s) are to be truncated to the output size.

Definition at line 368 of file dist_file_io.hpp.

References FEAT::BinaryStream::data(), FEAT::BinaryStream::size(), and write_ordered().

◆ write_ordered() [3/4]

static void FEAT::DistFileIO::write_ordered	(	const void *	buffer,
		const std::size_t	size,
		const String &	filename,
		bool	truncate = `true`
	)

inlinestatic

Writes a buffer into a common binary file in rank order.

This function write a single common binary file, where the individual processes write their outputs in ascending order by their rank.

Note: This function is effectively a wrapper around MPI_File_write_ordered.

Parameters

[in]	buffer	A transient pointer to the binary buffer that is to be written. Must not be `nullptr`.
[in]	size	The size of this process's buffer in bytes. May differ on each process.
[in]	filename	The name of the common output file. Must be the same on all calling processes.
[in]	comm	The communicator to be used for synchronization. Ignored if compiled without MPI.
[in]	truncate	Specifies whether the output file(s) are to be truncated to the output size.

Definition at line 342 of file dist_file_io.hpp.

References FEAT::Dist::Comm::world(), and write_ordered().

◆ write_ordered() [4/4]

void FEAT::DistFileIO::write_ordered	(	const void *	buffer,
		const std::size_t	size,
		const String &	filename,
		const Dist::Comm &	comm,
		bool	truncate = `true`
	)

static

Writes a buffer into a common binary file in rank order.

This function write a single common binary file, where the individual processes write their outputs in ascending order by their rank.

Note: This function is effectively a wrapper around MPI_File_write_ordered.

Parameters

[in]	buffer	A transient pointer to the binary buffer that is to be written. Must not be `nullptr`.
[in]	size	The size of this process's buffer in bytes. May differ on each process.
[in]	filename	The name of the common output file. Must be the same on all calling processes.
[in]	comm	The communicator to be used for synchronization. Ignored if compiled without MPI.
[in]	truncate	Specifies whether the output file(s) are to be truncated to the output size.

Definition at line 466 of file dist_file_io.cpp.

References XASSERT.

Referenced by write_ordered().

◆ write_sequence() [1/4]

static void FEAT::DistFileIO::write_sequence	(	BinaryStream &	stream,
		const String &	pattern,
		bool	truncate = `true`
	)

inlinestatic

Writes a rank-indexed text file sequence.

Parameters

[out]	stream	A transient reference to the string stream whose contents are to be written to the file.
[in]	pattern	The pattern that is to be used for filename generation.
[in]	comm	The communicator to be used for synchronization. Ignored if compiled without MPI.
[in]	truncate	Specifies whether the output file(s) are to be truncated to the output size.

Exceptions

FileNotCreated if the file could not be opened.

Definition at line 284 of file dist_file_io.hpp.

References FEAT::Dist::Comm::world(), and write_sequence().

◆ write_sequence() [2/4]

void FEAT::DistFileIO::write_sequence	(	BinaryStream &	stream,
		const String &	pattern,
		const Dist::Comm &	comm,
		bool	truncate = `true`
	)

static

Writes a rank-indexed binary file sequence.

This function writes a sequence of files, where each rank writes a single indexed file.

Parameters

[out]	stream	A transient reference to the binary stream whose contents are to be written to the file.
[in]	pattern	The pattern that is to be used for filename generation.
[in]	comm	The communicator to be used for synchronization. Ignored if compiled without MPI.
[in]	truncate	Specifies whether the output file(s) are to be truncated to the output size.

Exceptions

FileNotCreated if the file could not be opened.

Definition at line 439 of file dist_file_io.cpp.

References _rankname(), and _write_file().

◆ write_sequence() [3/4]

static void FEAT::DistFileIO::write_sequence	(	std::stringstream &	stream,
		const String &	pattern,
		bool	truncate = `true`
	)

inlinestatic

Writes a rank-indexed text file sequence.

Parameters

[out]	stream	A transient reference to the string stream whose contents are to be written to the file.
[in]	pattern	The pattern that is to be used for filename generation.
[in]	comm	The communicator to be used for synchronization. Ignored if compiled without MPI.
[in]	truncate	Specifies whether the output file(s) are to be truncated to the output size.

Exceptions

FileNotCreated if the file could not be opened.

Definition at line 256 of file dist_file_io.hpp.

References FEAT::Dist::Comm::world(), and write_sequence().

◆ write_sequence() [4/4]

void FEAT::DistFileIO::write_sequence	(	std::stringstream &	stream,
		const String &	pattern,
		const Dist::Comm &	comm,
		bool	truncate = `true`
	)

static

Writes a rank-indexed text file sequence.

Parameters

[out]	stream	A transient reference to the string stream whose contents are to be written to the file.
[in]	pattern	The pattern that is to be used for filename generation.
[in]	comm	The communicator to be used for synchronization. Ignored if compiled without MPI.
[in]	truncate	Specifies whether the output file(s) are to be truncated to the output size.

Exceptions

FileNotCreated if the file could not be opened.

Definition at line 434 of file dist_file_io.cpp.

References _rankname(), and _write_file().

Referenced by FEAT::Geometry::ExportVTK< Mesh_, cell_dim_ >::write(), and write_sequence().

Member Data Documentation

◆ magic_combined

constexpr std::uint64_t FEAT::DistFileIO::magic_combined = 0x4644433354414546ull

staticconstexpr

Magic number for combined distributed files as used by read_combined() and write_combined()

This magic number represents the ASCII-string "FEAT3CDF" encoded as a little endian uint64.

Definition at line 127 of file dist_file_io.hpp.

Referenced by read_combined(), and write_combined().

The documentation for this class was generated from the following files:

kernel/util/dist_file_io.hpp
kernel/util/dist_file_io.cpp

Static Public Member Functions

Static Public Attributes

Static Protected Member Functions

Detailed Description

Member Function Documentation

◆ _rankname()

◆ _read_file() [1/2]

◆ _read_file() [2/2]

◆ _write_file() [1/2]

◆ _write_file() [2/2]

◆ read_combined() [1/2]

◆ read_combined() [2/2]

◆ read_common() [1/4]

◆ read_common() [2/4]

◆ read_common() [3/4]

◆ read_common() [4/4]

◆ read_ordered() [1/2]

◆ read_ordered() [2/2]

◆ read_sequence() [1/4]

◆ read_sequence() [2/4]

◆ read_sequence() [3/4]

◆ read_sequence() [4/4]

◆ write_combined() [1/2]

◆ write_combined() [2/2]

◆ write_ordered() [1/4]

◆ write_ordered() [2/4]

◆ write_ordered() [3/4]

◆ write_ordered() [4/4]

◆ write_sequence() [1/4]

◆ write_sequence() [2/4]

◆ write_sequence() [3/4]

◆ write_sequence() [4/4]

Member Data Documentation

◆ magic_combined