- only affected v2406. Root cause is #3281

Mark OLESEN authored 10 months ago and Kutalmış Berçin committed 10 months ago

- previous support for file appending (largely unused) always
  specified opening with the std::ios_base::app flag.

  Now differentiate between append behaviours:

  APPEND_APP
  ~~~~~~~~~~
  Corresponds to std::ios_base::app behaviour:

  - Existing files will be preserved and a seek-to-end is performed at
    every write. With this mode seeks/repositioning within the file
    will effectively be ignored on output.

  APPEND_ATE
  ~~~~~~~~~~
  Largely approximates std::ios_base::ate behaviour:

  - Existing files will be preserved and a seek-to-end is performed
    immediately after opening, but not subsequently. Can use seekp()
    to overwrite parts of a file.

- support wantedType for localIOdictionary::readContents()

- add readContents() for GlobalIOList, GlobalIOField

- delay construction of message buffer

- OStringStream count() method to test if anything has been streamed

STYLE: explicit use of std::ios_base in IOstreams

- document the return information of set flag methods

- can be used with this type of code:

  ITstream* streamPtr = dict.findStream(name);
  if (streamPtr)
  {
      auto& is = *streamPtr;
      ...
  }

  versus:

  const entry* eptr = dict.findEntry(name);
  if (eptr && eptr->isStream())
  {
      auto& is = eptr->stream();
      ...
  }

ENH: add findStream(), streamPtr(), isStream() to dictionary search

- symmetric with findDict(), dictPtr(), isDict() methods

STYLE: use findDict() instead of found() + subDict() pairing

COMP: define is_globalIOobject trait at top of IOobject header

- more visibility, permits reuse for specializations etc.

- the maxCommsSize variable is used to 'chunk' large data transfers
  (eg, with PstreamBuffers) into a multi-pass send/recv sequence.

  The send/recv windows for chunk-wise transfers:

      iter    data window
      ----    -----------
      0       [0, 1*chunk]
      1       [1*chunk, 2*chunk]
      2       [2*chunk, 3*chunk]
      ...

  Since we mostly send/recv in bytes, the current internal limit
  for MPI counts (INT_MAX) can be hit rather quickly.

  The chunking limit should thus also be INT_MAX, but since it is
  rather tedious to specify such large numbers, can instead use

      maxCommsSize = -1

  to specify (INT_MAX-1) as the limit.
  The default value of maxCommsSize = 0 (ie, no chunking).

Note
~~~~
  In previous versions, the number of chunks was determined by the
  sender sizes. This required an additional MPI_Allreduce to establish
  an overall consistent number of chunks to walk. This additional
  overhead each time meant that maxCommsSize was rarely actually
  enabled.

  We can, however, instead rely on the send/recv buffers having been
  consistently sized and simply walk through the local send/recvs until
  no further chunks need to be exchanged. As an additional enhancement,
  the message tags are connected to chunking iteration, which allows
  the setup of all send/recvs without an intermediate Allwait.

ENH: extend UPstream::probeMessage to use int64 instead of int for sizes

- avoids polluting standard output for utilities such as
  foamDictionary etc

- the timeSelector is often used to select single or multiple times
  (eg, for post-processing). However, there are a few applications
  where only a *single* time should be selected and set.

  These are now covered by this type of use:

      timeSelector::addOptions_singleTime();  // Single-time options
      ...
      // Allow override of time from specified time options, or no-op
      timeSelector::setTimeIfPresent(runTime, args);

   In some cases, if can be desirable to force starting from the
   initial Time=0 when no time options have been specified:

      // Set time from specified time options, or force start from Time=0
      timeSelector::setTimeIfPresent(runTime, args, true);

   These changes make a number of includes redundant:

     * addTimeOptions.H
     * checkConstantOption.H
     * checkTimeOption.H
     * checkTimeOptions.H
     * checkTimeOptionsNoConstant.H

ENH: add time handling to setFields, setAlphaField (#3143)

    Co-authored-by: Johan Roenby <>

STYLE: replace instant("constant") with instant(0, "constant")

- avoids relying on atof parse behaviour returning zero

- not allowed in C++20

COMP: avoid hidden overloaded-virtual (edgeMesh, surfMesh)

- PstreamBuffers are nonBlocking by default, so no need to re-specify

- "buffered" corresponds to MPI_Bsend (buffered send),
  whereas the old name "blocking" is misleading since the
  regular MPI_Send also blocks until completion
  (ie, buffer can be reused).

ENH: IPstream::read() returns std::streamsize instead of label (#3152)

- previously returned a 'label' but std::streamsize is consistent with
  the input parameter and will help with later adjustments.

- use <label> instead of <int> for internal accounting of the message
  size, for consistency with the underyling List<char> buffers used.

- improve handling for corner case of IPstream receive with
  non-blocking, although this combination is not used anywhere

- return autoPtr<token::compound> instead of the derived type,
  otherwise cannot easily construct a token from it

ENH: additional typed version of refCompoundToken()

- symmetric with typed version of transferCompoundToken()
  and isCompound()

- add ITstream::findCompound<Type>() method.
  Useful for searching within token streams

- UPstream::Communicator is similar to UPstream::Request to
  wrap/unwrap MPI_Comm. Provides a 'lookup' method to transcribe
  the internal OpenFOAM communicator tracking to the opaque wrapped
  version.

- provide an 'openfoam_mpi.H' interfacing file, which includes
  the <mpi.h> as well as casting routines.

  Example (caution: ugly!)

     MPI_Comm myComm =
         PstreamUtils::Cast::to_mpi
         (
             UPstream::Communicator::lookup(UPstream::worldComm)
         );

- adds consistency with regular point-to-point parallel streams.

ENH: add ITstream::tokens() methods

- useful, for example, to disambiguate constructing tokenList from
  a ITstream.

  ITstream& is = otherDict.lookup("original");

  tokenList deepCopy(is);  // Error: from Istream or tokenList??
  tokenList deepCopy(is.tokens());  // OK: from tokenList

- same as append() did, but with more consistent names

STYLE: replace special purpose append() with container method

STYLE: update code style

- Delete() will perform a 'checkOut()' which does the following:
  * remove the object from the registry
  * delete the pointer (if owned by the registry)

- Release() does the following:
  * transfer ownership of the pointer (if owned by the registry)

- Store() does the following:
  * transfer ownership of the pointer to the registry

ENH: use UPtrList of sorted objects for MeshObject updates

- few allocations and lower overhead than using a HashTable,
  ensures the same walk order over the objects (in parallel)

STYLE: adjust meshObject debug statements

- findStrings, findMatchingStrings now mostly covered by matching
  intrinsics in wordRe and wordRes.

  Add static wordRes match() and matching() variants

COMP: remove stringListOps include from objectRegistry.H

- was already noted for removal (NOV-2018)

- an example of the new, more succinct refConstCast version:

      auto& abc = refConstCast<adjointVectorBoundaryCondition>(Uab);

  older:
      adjointVectorBoundaryCondition& abc =
          refCast<adjointVectorBoundaryCondition>
          (
              const_cast<fvPatchVectorField&>(Uab)
          );
  or:
      adjointVectorBoundaryCondition& abc =
          const_cast<adjointVectorBoundaryCondition&>
          (
              refCast<const adjointVectorBoundaryCondition>(Uab)
          );

- an example of the new, more succinct isA_constCast version:

      auto* acapPtr = isA_constCast<fieldType>(abf[patchi]);

      if (acapPtr)
      {
          auto& acap = *acapPtr;
          ...
      }

  older:
      if (isA<fieldType>(abf[patchi]))
      {
          fieldType& acap =
              const_cast<fieldType&>
              (
                  refCast<const fieldType>(abf[patchi])
              );
          ...
      }

STYLE: remove spurious 'const' qualifier from isA<> use

- previously would always return "constant" as the instance for
  an optional dir/file that wasn't found.
  However, this meant retesting to screen out false positives.
  Now support an additional parameter
      'bool constant_fallback = ...'
  to return "constant" or an empty word.

  The method signature changes slightly with a new optional bool
  parameter:

      //! Return \c "constant" instead of \c "" if the search failed
      const bool constant_fallback = true

ENH: code consolidation for findInstancePath

- relocate from Time to TimePaths and provide an additional static
  version that is reused in fileOperations

BUG: distributedTriSurfaceMesh:::findLocalInstance broken (#3135)

- was not checking the parent at all.

COMP: remove unused findInstancePath(const fileName&, ..) method

- leave 'readContents' method name for exposed (public) methods.
  Generally not a problem, but can confuse the compiler when various
  public/private versions are available with the same number of
  parameters.

STYLE: adjust meshObject debug statements

- regIOobject::store(std::unique_ptr<...>&& ptr)
- IOobjectList::add(std::unique_ptr<...>&& ptr)

STYLE: io.globalCaseName() instead of io.time().globalCaseName() [#3007]

- the rootProcNo is usually == UPstream::masterNo()

- particularly useful in these combinations:

  1.
      OCharStream buf;
      // populate

      ISpanStream is(buf.view());
      // parse

  2.
      // read from file
      ifile.getLine(str);

      ISpanStream is(str);
      // parse

  These avoid making a copy of the character content, compared to
  versions with stringstream:

      OStringStream buf;
      IStringStream is(buf.str());

- reads file contents into a DynamicList<char>, which can then be
  broadcast, moved to a ICharStream etc.

ENH: eliminate unnecessary duplicate communicator

- in globalMeshData previously had a comm_dup hack to avoid clashes
  with deltaCoeffs calculations. However, this was largely due to a
  manual implementation of reduce() that used point-to-point
  communication. This has since been updated to use an MPI_Allreduce
  and now an MPI_Allgather, neither of which need this hack.

ENH: add rank() method for compound tokens

ENH: add IOstream::minPrecision(unsigned)

- reduced typing, more expressive, no namespace ambiguity with max()

    new: IOstream::minPrecision(10);
    old: IOstream::defaultPrecision(max(10u, IOstream::defaultPrecision()));

STYLE: namespace qualify min/max for some buffer sizing [clang/hipp]

- avoid string conversion/concatenation unless profiling hooks
  are possible (ie, active or Extrae is loaded).

- example use:

      mesh.newIOobject(name, { IOobject::REGISTER });

  vs

      mesh.newIOobject
      (
          name,
          IOobject::NO_READ,
          IOobject::NO_WRITE,
          IOobject::REGISTER
      );

- add count() member for output span streams (consistency)

- ITstream construct/parse from span/view

COMP: remove old/unused first()/last() methods from SubStrings

- can use UList signature since the routines do not resize the list
  or attempt to broadcast it: useful for SubList handling.

ENH: add IPstream/OPstream send/recv static methods

Mark OLESEN authored 1 year ago and Mattijs Janssens committed 1 year ago

- the old Pstream::scatter routines (which were largely a misnomer)
  have been superseded by various broadcast routines, but were left in
  the code with #ifndef/#ifdef Foam_Pstream_scatter_nobroadcast
  guards. Now noisily deprecate them, and remove the old manual tree
  communication in favour of MPI broadcast and/or
  serialize/de-serialize with wrapped Pstream::broadcast

- consolidate various gather methods to include the communication
  structure directly. No functional change, but reduces the number of
  methods.

ENH: add parallel guard to UPstream::whichCommunication() method

- returns List::null() as the schedule for non-parallel instead
  of an inappropriate linear or tree schedule

ENH: Pstream::listGatherValues, Pstream::listScatterValues

- like the existing UPstream versions but supporting non-contiguous