From 7f88b344adb92434814c82c839a513fc1ccf3b11 Mon Sep 17 00:00:00 2001
From: Anton Khirnov <anton@khirnov.net>
Date: Mon, 20 Jan 2020 15:25:21 +0100
Subject: mg2d: add a designated error code for reaching maxiter

Allows to reliably distinguish it from other error cases. Also specify
that the values of u are defined for this error code.
---
 mg2d.c           |  2 +-
 mg2d.h           | 12 ++++++++++--
 mg2d_constants.h |  9 ++++++++-
 3 files changed, 19 insertions(+), 4 deletions(-)

diff --git a/mg2d.c b/mg2d.c
index e0a83ed..b669569 100644
--- a/mg2d.c
+++ b/mg2d.c
@@ -1149,7 +1149,7 @@ int mg2d_solve(MG2DContext *ctx)
         res_prev = res_cur;
     }
 
-    ret = -EDOM;
+    ret = MG2D_ERR_MAXITER_REACHED;
     mg2di_log(&priv->logger, MG2D_LOG_ERROR,
               "Maximum number of iterations (%d) reached\n", ctx->maxiter);
 fail:
diff --git a/mg2d.h b/mg2d.h
index 867d77e..01698a8 100644
--- a/mg2d.h
+++ b/mg2d.h
@@ -163,7 +163,9 @@ typedef struct MG2DContext {
      * Allocated and initialized to zero by the solver in mg2d_solver_alloc(),
      * owned by the solver.
      * May be filled by the caller before solving to set the initial guess.
-     * Afterwards updated in mg2d_solve().
+     * Afterwards updated by mg2d_solve() if it returns 0,
+     * MG2D_ERR_MAXITER_REACHED or MG2D_ERR_DIVERGE. If mg2d_solve() returnes
+     * another error code, the contents of u are unspecified.
      */
     double   *u;
     /**
@@ -265,7 +267,13 @@ MG2DContext *mg2d_solver_alloc_mpi(MPI_Comm comm, const size_t local_start[2],
  *
  * This function may be called more than once.
  *
- * @return 0 on success, a negative error code on failure.
+ * @return
+ *   - 0 on success
+ *   - MG2D_ERR_MAXITER_REACHED if desired tolerance was not reached after
+ *     maximum allowed number of iterations were performed. The final
+ *     value of the solution is still exported in ctx->u.
+ *   - MG2D_ERR_DIVERGE if the iteration process has diverged.
+ *   - another negative error code on other types of failure
  */
 int mg2d_solve(MG2DContext *ctx);
 /**
diff --git a/mg2d_constants.h b/mg2d_constants.h
index aa3d5cb..a197240 100644
--- a/mg2d_constants.h
+++ b/mg2d_constants.h
@@ -20,7 +20,14 @@
 #define MG2D_CONSTANTS_H
 
 enum MG2DError {
-    MG2D_ERR_DIVERGE = -0xff00,
+    /**
+     * The solver has diverged.
+     */
+    MG2D_ERR_DIVERGE         = -0xff00,
+    /* Maximum number of iterations has been executed without the solution
+     * reaching desired tolerance.
+     */
+    MG2D_ERR_MAXITER_REACHED = -0xff01,
 };
 
 /**
-- 
cgit v1.2.3