CommonIO Class Reference

Class that provides globally accessible stream definitions. More...

#include <CommonIO.h>

List of all members.

Public Methods
	CommonIO ()
	Constructor.
virtual	~CommonIO ()
	Destructor - flushes the I/O streams.
virtual int	verbosity (const int level)
	Returns true if I/O is allowed from this process.
void	setDebug (int level)
	Set the debugging field.
Static Public Methods
void	begin ()
	Begin using CommonIO to redirect IO.
void	begin_buffered ()
	Begin using CommonIO to redirect IO using buffered IO.
void	end ()
	End the use of CommonIO to redirect IO.
void	map_off ()
	Turn off CommonIO mapping (by default it is on).
void	map_on ()
	Turn on the CommonIO mapping.
void	reset ()
	Resets the I/O streams to the C++ standard streams.
void	setIORank (int Rank_)
	Set the rank of the processor that is allowed to do I/O.
void	setIOFlush (int flush_)
	Set the flag to indicate whether I/O is explicitly flushed.
int	rank ()
	Rank of the current process.
int	io_rank ()
	Rank of the current process.
int	numProcs ()
	Number of processes.
ostream &	outs ()
	Returns a stream that 'wraps' the common_cout.
ostream &	errs ()
	Returns a stream that 'wraps' the common_cerr.
istream &	ins ()
	Returns a stream that 'wraps' the common_cin.
void	set_streams (ostream *cout_, ostream *cerr_, istream *cin_)
	The function for reseting the streams. Null streams are unchanged.
void	set_cout (ostream *cout_)
	The function for reseting the cout stream.
void	set_cerr (ostream *cerr_)
	The function for reseting the cerr stream.
void	set_cin (istream *cin_)
	The function for reseting the cin stream.
void	set_ofile (const char *ofile)
	Redirect ucout/ucerr I/O to seperate output streams for each processor.
void	begin_tagging ()
	TODO.
void	begin_tagging (const int numDigits_)
	TODO.
void	end_tagging ()
	TODO.
void	flush ()
	TODO.
void	sync_stdio ()
	Synchronized the C++ streams with the STDIO streams.
Public Attributes
int	debug
	Specifies the debugging level (0 means no debugging).
Static Public Attributes
int	numDigits
	The maximum number of digits needed to print the I/O counter.
ostream *	std_cout
	static reference to the system cout stream.
ostream *	std_cerr
	static reference to the system cerr stream.
istream *	std_cin
	static reference to the system cin stream.
ostream **	MapCout
	The C++ stream object used to process ucout stream information.
ostream **	MapCerr
	The C++ stream object used to process ucerr stream information.
istream **	MapCin
	The C++ stream object used to process ucin stream information.
Static Protected Methods
void	end_all ()
	End the use of CommonIO to redirect IO, completely reseting.
Static Private Methods
ostream &	o_stream (const int flag)
	Sets up internal variables and returns an output stream.
void	IOflush ()
	TODO.
void	flush_stream (strstream &stream, ostream *tmp)
	TODO.
void	reset_map ()
	Resets the values of the Map# streams based on the current state.
Static Private Attributes
int	io_mapping
	Flag which indicates whether CommonIO is used for IO mapping.
int	io_buffering
	Integer of the number of nest CommonIO blocks that are buffered.
int	begin_end_counter
	The number of calls to CommonIO::begin() that haven't ended.
int	IO_Rank
	The rank of the processor that is allowed to do debugging I/O.
int	tagging
	TODO.
int	nref
	TODO.
int	flush_flag
	Flag that indicates whetner.
int	seqNum
	The number of I/O lines that have been printed.
int	Rank
	The rank of the current process.
int	Size
	The number of parallel processes.
int	stream_flag
	Output stream flag: 0 = common_cout, 1 = common_cerr.
int	header_flag
	If true, then try to print the rank header before next character.
ofstream *	common_ofstr
	the common ofstream.
ostream *	common_cout
	the common cout stream.
ostream *	common_cerr
	the common cerr stream.
istream *	common_cin
	the common cin stream.
strstream *	pStrCout
	Pointer to the C++ stream object used to process cout stream info.
strstream *	pStrCerr
	Pointer to the C++ stream object used to process cerr stream info.
Friends
void	cppMessage_abort ()
UTILIB_API ostream &	Flush (ostream &outstr)
	TODO.

---

Detailed Description

Class that provides globally accessible stream definitions.

This allows I/O to be routed through a common point in the code. Including this class allows I/O from the standard ostreams cout and cerr to be implicitly routed through a strstream buffer, which is used to add tagging information. Further, the standard ostreams can be globally replaced with other ostreams, which allows for a single point of control for routing all I/O in a program through a single string (e.g. to a file via an ofstream).

Including the CommonIO.h header file provides macro-based definitions for the symbols ucout, ucerr and ucin. By default, these symbols are mapped to the standard C++ I/O streams. I/O can be directed to/from other streams using the set_streams, set_cout, set_cerr and set_cin methods. CommonIO also allows users to masking these streams, which adds information about the processor ID and/or line number of the I/O. To begin masking, the user executes CommonIO::begin(), and similarly CommonIO::end() is called to end the masking of these streams. For example:

    CommonIO::begin()
    ucout << "This text is rerouted through CommonIO's streams" << endl;
    CommonIO::end()
   

Note that calls to CommonIO::begin() and CommonIO::end() can be nested, enabling subroutines to use CommonIO without worrying whether the IO has already been redirected. However, note that the formatting options for CommonIO streams described below are NOT reset after a call to CommonIO::end(); the user is responsible for reseting the state of the CommonIO streams after their use.

Because a begin-end block can be nested in this fashion, calling CommonIO::end() does not necessarily turn off IO mapping; IO mapping could have been initialed from an enclosing begin-end block. The method CommonIO::map_off() can be called to explicitly turn off IO mapping regardless whether mapping has been initiated by a previous call to CommonIO::begin(). CommonIO::map_on() must be used to restart IO mapping; a subsequent call to CommonIO::begin() will be masked by the the CommonIO::off() method. Finally, note that an error is detected if a matching Common()end() is not called for every CommonIO::begin() when the last CommonIO object is destructed.

CommonIO provides routines that manage parallel debugging, prepending tagging information, and providing a global debugging flag. Tagging information is prepended after begin_tagging() is called. An optional argument specifies the value of the the numDigits variable (by default numDigits=0). The format of the prepended IO is:

    [r]-000ii
   

where 'r' is the rank of the current process and 'ii' is the index of the current IO; the index field has numDigits digits. Tagging is stopped when end_tagging() is called.

To facilitate tagging, the ucout/ucerr macros map to strstream buffers. When the stream is flushed by calling 'CommonIO::flush()' or by using the IO manipulator 'Flush',

 
        ucout << Flush
   

the IO is processed to insert the rank information after every end-of-line in the stream. Using this facility makes it difficult to support the 'flush' method for streams, as <stream>.flush() gets mapped to a flush operation on an strstream object. This does NOT flush the <stream> object as with standard ucout/ucerr streams. Consequently, the 'Flush' IO manipulator has been created to provide a convenient means of flushing CommonIO streams.

CommonIO can also be used to buffer IO generated by a process. If CommonIO::begin_buffered() is called, then the IO is mapped via strstream objects, but the IO is not flushed until CommonIO::end() is called. If a new CommonIO begin/end block is started within a buffered begin/end block, IO within this block will continue to be buffered.

The setIORank() method can be used to limit debugging IO to a limited number of processors. By default, the verbosity() check allows all processors to perform IO. By calling setIORank(x), where x != rank(), future calls to verbosity() will return FALSE, thereby turning off debugging IO.

---

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

• CommonIO.h