Skip to content

Commit 8751d3d

Browse files
authored
Reduce error messages from IOStream
Reduces error messages and replaces most return codes in favor of immediate abort in IOStream routines. The exception is the read function which returns an error when fields are not found to support cases in which some fields may not be required. Developer guide has been updated to reflect the new interfaces and to document the read behavior.
2 parents 60bb4cc + 77fad1b commit 8751d3d

File tree

6 files changed

+175
-229
lines changed

6 files changed

+175
-229
lines changed

components/omega/doc/devGuide/IOStreams.md

Lines changed: 9 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,7 @@ been defined and the relevant data arrays have been attached to Fields and
4040
are available to access. At the end of a simulation, IOStreams must be
4141
finalized using
4242
```c++
43-
int Err = IOStream::finalize(ModelClock);
43+
IOStream::finalize(ModelClock);
4444
```
4545
so that any final writes can take place for the OnShutdown streams and to
4646
deallocate all defined streams and arrays. If a stream needs to be removed
@@ -52,26 +52,29 @@ before that time, an erase function is provided:
5252
For most output streams, we provide a writeAll interface that should be placed
5353
at an appropriate time during the time step loop:
5454
```c++
55-
int Err = IOStream::writeAll(ModelClock);
55+
IOStream::writeAll(ModelClock);
5656
```
5757
This function checks each write stream and writes the file if it is time, based
5858
on a time manager alarm that is defined during initialization for each stream
5959
based on the time frequency in the streams configuration. After writing the
6060
file, the alarm is reset for the next write time. If a file must be written
6161
outside of this routine, a single-stream write can take place using:
6262
```c++
63-
int Err = IOStream::write(StreamName, ModelClock);
63+
IOStream::write(StreamName, ModelClock);
6464
```
6565

6666
Reading files (eg for initialization, restart or forcing) does not often
6767
take place all at once, so no readAll interface is provided. Instead, each
6868
input stream is read using:
6969
```c++
70-
int Err = IOStream::read(StreamName, ModelClock, ReqMetadata);
70+
Error Err = IOStream::read(StreamName, ModelClock, ReqMetadata);
7171
```
72-
where ReqMetadata is a variable of type Metadata (defined in Field but
72+
The returned error code typically means that a field in the stream could
73+
not be found in the input file - most other errors abort immediately. The
74+
calling routine is then responsible for deciding what action to take.
75+
The ReqMetadata argument is a variable of type Metadata (defined in Field but
7376
essentially a ``std::map<std::string, std::any>`` for the name/value pair).
74-
This variable should incude the names of global metadata that are desired
77+
This variable should include the names of global metadata that are desired
7578
from the input file. For example, if a time string is needed to verify the
7679
input file corresponds to a desired time, the required metadata can be
7780
initialized with

0 commit comments

Comments
 (0)