ENH: added functionObject::execute(int) method

- this is a provision for defining execute actions that can be called
  largely independently of the normal time-loop constraints. This can
  be useful to provide hooks for sub-cycling, or to define an action
  that can be triggered manually or on some other event.

src/OpenFOAM/db/functionObjects/functionObject/functionObject.C

@@ -141,6 +141,12 @@ bool Foam::functionObject::read(const dictionary& dict)
 }
 
 
+bool Foam::functionObject::execute(const label)
+{
+    return true;
+}
+
+
 bool Foam::functionObject::end()
 {
     return true;

src/OpenFOAM/db/functionObjects/functionObject/functionObject.H

@@ -222,13 +222,19 @@ public:
         const word& name() const;
 
         //- Read and set the function object if its data have changed
-        virtual bool read(const dictionary&);
+        virtual bool read(const dictionary& dict);
 
         //- Called at each ++ or += of the time-loop.
         //  postProcess overrides the usual executeControl behaviour and
         //  forces execution (used in post-processing mode)
         virtual bool execute() = 0;
 
+        //- Execute using the specified subIndex.
+        //  The base implementation is a no-op.
+        //  \param subIndex an execution sub-index corresponding to a
+        //      sub-cycle or something similar.
+        virtual bool execute(const label subIndex);
+
         //- Called at each ++ or += of the time-loop.
         //  postProcess overrides the usual writeControl behaviour and
         //  forces writing always (used in post-processing mode)
@@ -245,9 +251,11 @@ public:
         virtual bool filesModified() const;
 
         //- Update for changes of mesh
+        //  The base implementation is a no-op.
         virtual void updateMesh(const mapPolyMesh& mpm);
 
         //- Update for changes of mesh
+        //  The base implementation is a no-op.
         virtual void movePoints(const polyMesh& mesh);
 };
 

src/OpenFOAM/db/functionObjects/functionObjectList/functionObjectList.C

@@ -32,6 +32,7 @@ License
 //#include "IFstream.H"
 #include "dictionaryEntry.H"
 #include "stringOps.H"
+#include "wordRes.H"
 #include "Tuple2.H"
 #include "etcFiles.H"
 #include "IOdictionary.H"
@@ -579,6 +580,7 @@ bool Foam::functionObjectList::execute()
             }
         }
     }
+
     // Force writing of state dictionary after function object execution
     if (time_.writeTime())
     {
@@ -600,6 +602,49 @@ bool Foam::functionObjectList::execute()
 }
 
 
+bool Foam::functionObjectList::execute(const label subIndex)
+{
+    bool ok = execution_;
+
+    if (ok)
+    {
+        forAll(*this, obji)
+        {
+            functionObject& funcObj = operator[](obji);
+
+            ok = funcObj.execute(subIndex) && ok;
+        }
+    }
+
+    return ok;
+}
+
+
+bool Foam::functionObjectList::execute
+(
+    const wordRes& functionNames,
+    const label subIndex
+)
+{
+    bool ok = execution_;
+
+    if (ok && functionNames.size())
+    {
+        forAll(*this, obji)
+        {
+            functionObject& funcObj = operator[](obji);
+
+            if (functionNames.match(funcObj.name()))
+            {
+                ok = funcObj.execute(subIndex) && ok;
+            }
+        }
+    }
+
+    return ok;
+}
+
+
 bool Foam::functionObjectList::end()
 {
     bool ok = true;

src/OpenFOAM/db/functionObjects/functionObjectList/functionObjectList.H

@@ -52,8 +52,10 @@ SourceFiles
 namespace Foam
 {
 
-class mapPolyMesh;
+// Forward declarations
 class argList;
+class mapPolyMesh;
+class wordRes;
 
 /*---------------------------------------------------------------------------*\
                      Class functionObjectList Declaration
@@ -94,19 +96,19 @@ class functionObjectList
         void createStateDict() const;
 
         //- Remove and return the function object pointer by name,
-        //  and returns the old index via the parameter.
+        //- and returns the old index via the parameter.
         //  Returns a nullptr (and index -1) if it didn't exist
-        functionObject* remove(const word&, label& oldIndex);
+        functionObject* remove(const word& key, label& oldIndex);
 
         //- Search the specified directory for functionObject
-        //  configuration files, add to the given map and recurse
+        //- configuration files, add to the given map and recurse
         static void listDir(const fileName& dir, HashSet<word>& foMap);
 
         //- Disallow default bitwise copy construct
-        functionObjectList(const functionObjectList&);
+        functionObjectList(const functionObjectList&) = delete;
 
         //- Disallow default bitwise assignment
-        void operator=(const functionObjectList&);
+        void operator=(const functionObjectList&) = delete;
 
 
 public:
@@ -114,7 +116,7 @@ public:
     // Static data members
 
         //- Default relative path to the directory structure
-        //  containing the functionObject dictionary files
+        //- containing the functionObject dictionary files
         static fileName functionObjectDictPath;
 
 
@@ -188,7 +190,7 @@ public:
         label findObjectID(const word& name) const;
 
         //- Print a list of functionObject configuration files in
-        //  user/group/shipped directories.
+        //- user/group/shipped directories.
         //  The search scheme allows for version-specific and
         //  version-independent files using the following hierarchy:
         //  - \b user settings:
@@ -205,7 +207,7 @@ public:
         static void list();
 
         //- Search for functionObject dictionary file in
-        //  user/group/shipped directories.
+        //- user/group/shipped directories.
         //  The search scheme allows for version-specific and
         //  version-independent files using the following hierarchy:
         //  - \b user settings:
@@ -258,6 +260,18 @@ public:
         //  forces execution (used in post-processing mode)
         bool execute();
 
+        //- Execute function objects using the specified subIndex.
+        //  \param subIndex an execution sub-index corresponding to a
+        //      sub-cycle or something similar
+        bool execute(const label subIndex);
+
+        //- Execute a subset of function objects using the specified subIndex.
+        //  \param functionNames names or regex of existing functions to
+        //      execute
+        //  \param subIndex an execution sub-index corresponding to a
+        //      sub-cycle or something similar
+        bool execute(const wordRes& functionNames, const label subIndex);
+
         //- Called when Time::run() determines that the time-loop exits
         bool end();
 

src/OpenFOAM/db/functionObjects/timeControl/timeControlFunctionObject.C

@@ -450,6 +450,18 @@ bool Foam::functionObjects::timeControl::execute()
 }
 
 
+bool Foam::functionObjects::timeControl::execute(const label subIndex)
+{
+    if (active())
+    {
+        // Call underlying function object directly
+        foPtr_->execute(subIndex);
+    }
+
+    return true;
+}
+
+
 bool Foam::functionObjects::timeControl::write()
 {
     if (active() && (postProcess || writeControl_.execute()))
@@ -726,11 +738,9 @@ bool Foam::functionObjects::timeControl::read(const dictionary& dict)
 
         return true;
     }
-    else
-    {
+
     return false;
 }
-}
 
 
 bool Foam::functionObjects::timeControl::filesModified() const

src/OpenFOAM/db/functionObjects/timeControl/timeControlFunctionObject.H

@@ -206,6 +206,9 @@ public:
             //  forces execution (used in post-processing mode)
             virtual bool execute();
 
+            //- Execute using the specified subIndex.
+            virtual bool execute(const label subIndex);
+
             //- Called at each ++ or += of the time-loop.
             //  postProcess overrides the usual writeControl behaviour and
             //  forces writing (used in post-processing mode)