Provide protocol for exchanging state with client

The state that is passed to the simulator object is directly
accessible without any encapsulation towards the client. After
the notification callback was introduced, this allows the client
to observe the state in the middle of a simulation.

However, it may be that the simulator has some internal state
which is not reflected in the state object because there is a
cost associated by flushing it into the TwophaseState format.

The notification is called back on every timestep, not just the
ones that will do reporting. It may even be that reporting is
done dynamically and is not known at the time of setup. (It is
more like a condition variable).

Consequently, flushing the state in every timestep is a bad
idea. This patch sets up a new method sync() which it is expected
that the notification will call if it needs the state for
reporting purposes.

Currently it is a no-op. It just establishes a protocol that
other, compatible implementations can also use.

opm/simulators/SimulatorIncompTwophase.cpp

@@ -136,6 +136,11 @@ namespace Opm
         return pimpl_->timestep_completed_;
     }
 
+    // empty default implementation, but provided in module; it is dangerous ta have
+    // this inlined in clients from the header, because then it can't be updated!
+    void SimulatorIncompTwophase::sync () {
+    }
+
     static void reportVolumes(std::ostream &os, double satvol[2], double tot_porevol_init,
                               double tot_injected[2], double tot_produced[2],
                               double injected[2], double produced[2],

opm/simulators/SimulatorIncompTwophase.hpp

@@ -110,8 +110,28 @@ namespace Opm
         /// sim.timestep_completed ().add <Foo, &Foo::bar> (f);
         /// sim.run (...);
         /// \endcode
+        ///
+        /// \note
+        /// Registered callbacks should call the sync() method before
+        /// accessing the state that was passed into the run() method.
+        ///
+        /// \see Opm::SimulatorIncompTwophase::sync
         Event& timestep_completed ();
 
+        /// Notify the simulator that a callback has an interest in reading
+        /// for reporting purposes the contents of the state argument that
+        /// was passed to the run() method. The simulator will then flush
+        /// any internal state which is currently not reflected in it.
+        ///
+        /// \note
+        /// This should only be called from within a notification which has
+        /// been setup with timestep_completed(). Avoid calling this method
+        /// outside of run().
+        ///
+        /// \see Opm::SimulatorIncompTwophase::run,
+        ///      Opm::SimulatorIncompTwophase::timestep_completed
+        void sync ();
+
     private:
         struct Impl;
         // Using shared_ptr instead of unique_ptr since unique_ptr requires complete type for Impl.